Computer Inter@ctive 17

home *** CD-ROM | disk | FTP | other *** search

/ Computer Inter@ctive 17 / Computer Interactive cdrom 17 - gen 99.iso / ZDNETIT / CONTENT / OPTIVDOS.ZIP / DOC.ZIP / FUNCREF.TXT < prev next >

Wrap

Text File | 1998-10-21 | 385.8 KB | 6,776 lines

OOOOOO VV VV OO OO PPPPPPP TTTTTTTT II VV VV EEEEEE CCCCCC OO OO PP PP TT II VV VV EE CC OO OO PPPPPPP TT II VV VV EEEEEE CC OO OO PP TT II VVV EE CC OOOOOO PP TT II V EEEEEE CCCCCC OptiVec Version 1.2 for Borland C++ (Version 3.0 or higher) Part Two: Function Reference for VectorLib Dr. Martin Sander Software Development Sertürnerstr. 11 D-37085 Göttingen Germany e-mail: MartinSander@Bigfoot.com http://www.optivec.com **************************************************************************** S e c o n d P a r t : File FUNCREF.TXT !! This is an ASCII text file! It is best viewed with a simple !! !! DOS editor. !! !! If you load this file into a word processor under Windows, you !! !! must use the filter "DOS text". !! !! Alternatively, you may use FCONVERT (shipped with Borland C++) to !! !! convert from ASCII (OEM) into the ANSI character set. !! !! Preferrably use the lettertype CourierNew 10 pt. !! A general description of VectorLib is given in the F i r s t P a r t of this documentation, in the file HANDBOOK.TXT. Chapter 1.2 of that file contains the licence terms. Copyright for the Software and its documentation (C) 1996-1998 Martin Sander **************************************************************************** * * ******* 8. Alphabetical Reference ******* * * **************************************************************************** The functions are alphabetically ordered, with the prefixes being neglected for the ordering. The heading of each entry lists all the versions available of a specific function. For example, the "abs" family of functions exists in vectorized versions for - the three real-number data types float, double, and extended (long double) with the prefixes VF_, VD_, and VE_, - for the three complex-number data types (prefixes VCF_, VCD_, and VCE_), - and for the signed integer data types int, short int, long int and quad (prefixes VI_, VSI_, VLI_, and VQI); unsigned numbers are, by their very definition, always positive, and it makes no sense to define the operation "abs" for them; consequently, the VU_, VUS_, VUL_, and VUI_ versions are missing. The lines following the heading describe the use of the respective functions in greater detail: Syntax In most cases, only the VF_ version is described. All other versions are exactly analogous; one has only to replace the data types float and fVector by the appropriate ones and replace the VF... include file by the one belonging to the desired data type. Description Often, for the sake of simplicity, the brackets around vector element indices are left away. If not stated otherwise, all vector elements from the zero'th up to the last one (with the index size-1) are subjected to the respective operation described. Thus, a formula like Yi = │ Xi │ is to be understood as an abbreviation for Y[i] = │ X[i] │, i=0,...,size-1 or, written as a loop: for( i=0; i<size; i++ ) Y[i] = fabs( X[i] ); Error handling All types of errors are listed which are detected and handled. The default result is given in each case. In case of any detected floating-point errors, _matherr or _matherrl are called (see chapter 5.3). Although we do not recommend that, the user may modify _matherr and _matherrl such as to specify other results than those suggested. Return value The return value of the respective function is mentioned here. See also References to functions without a prefix "V..." refer to the documentation of Borland C. References to chapters 1. to 7. refer to the F i r s t P a r t of this documentation. See the file HANDBOOK.TXT. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_abs VD_abs VE_abs │ │ VCF_abs VCD_abs VCE_abs │ │ VI_abs VSI_abs VLI_abs VQI_abs │ └────────────────────────────────────────────────────────────────────────────┘ Function Absolute value Syntax #include <VFmath.h> int VF_abs( fVector Y, fVector X, ui size ); (similarly VD_, VE_, VSI_, VI_, VLI_, VQI_) int VCF_abs( fVector Y, cfVector X, ui size ); (similarly VCD_, VCE_) Description Real and integer versions: Yi = │ Xi │ VSI_, VI_, and VLI_ versions only: due to the implicit modulo-2**n arithmetics, the absolute value of the most negative numbers possible ( -32768 for short, -2147483648 for long) is stored as the same negative (!) number (-32768 or -2147483648, resp.). Complex versions: Yi = sqrt( Xi.Re² + Xi.Im² ) For the complex versions, note that the result is real- valued. The same result may also be obtained slightly faster, but without error handling, using VF_CtoAbs. Error handling Real and integer versions: no errors should occur; Complex versions: OVERFLOW errors lead to the default result +HUGE_VAL. Return value Floating-point versions: 0, if error-free, otherwise != 0. The integer versions have no return value. See also VF_neg, VCF_abs, VCF_conj ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_absmax VD_absmax VE_absmax │ │ VCF_absmax VCD_absmax VCE_absmax │ └────────────────────────────────────────────────────────────────────────────┘ Function Largest absolute value within one vector Syntax #include <VFstd.h> float VF_absmax( fVector X, ui size ); (similarly VD_, VE_) float VCF_absmax( cfVector X, ui size); (similarly VCD_, VCE_) Description The absolute values of all elements of a vector are compared and the largest returned. For complex numbers, the magnitudes of the elements are compared and the largest returned. In order to find the greatest real and imaginary parts separately, please use VCF_absmaxReIm. Error handling none Return value maximum absolute value encountered. See also VF_max, VF_absmin, VF_runmax, VF_absmaxind, VCF_absmaxReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_absmaxind VD_absmaxind VE_absmaxind │ │ VCF_absmaxind VCD_absmaxind VCE_absmaxind │ └────────────────────────────────────────────────────────────────────────────┘ Function Largest absolute value and its index Syntax #include <VFstd.h> float VF_absmaxind( ui *Ind, fVector X, ui size ); (similarly VD_, VE_) float VCF_absmaxind( ui *Ind, cfVector X, ui size ); (similarly VCD_, VCE_) Description The absolute values of all elements of a vector are compared and the largest returned. For complex numbers, the magnitudes of the elements are compared and the largest returned. The index of this maximum is stored at the address given by Ind. In case of more than one element with the same maximum value, the lowest index is chosen. Error handling none Return value maximum absolute value encountered. See also VF_maxind, VF_absmax, VF_runmax, VF_maxind, VCF_absmaxReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_absmaxReIm VCD_absmaxReIm VCE_absmaxReIm │ └────────────────────────────────────────────────────────────────────────────┘ Function Separate determination of the largest absolute values of the real and imaginary parts occurring in a complex vector. Syntax #include <VCFstd.h> fComplex VCF_absmaxReIm( cfVector X, ui size ); (similarly VCD_, VCE_) Description The absolute values of the real parts of all vector elements are compared with each other and the largest one is returned as the real part of the result. Similarly, the absolute values of all the imaginary parts are compared with each other and the largest one is returned as the imaginary part of the result. Generally, the result is made up from different elements of the vector. Error handling none Return value Largest absolute real and imaginary parts, combined into one complex number. See also VCF_maxReIm, VCF_absminReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_absmin VD_absmin VE_absmin │ │ VCF_absmin VCD_absmin VCE_absmin │ └────────────────────────────────────────────────────────────────────────────┘ Function Smallest absolute value within one vector Syntax #include <VFstd.h> float VF_absmin( fVector X, ui size ); (similarly VD_, VE_) float VCF_absmin( cfVector X, ui size ); (similarly( VCD_, VCE_) Description The absolute values of all elements of a vector are compared and the smallest returned. For complex numbers, the magnitudes of the elements are compared and the smallest returned. In order to find the smallest real and imaginary parts separately, please use VCF_absminReIm. Error handling none Return value minimum absolute value encountered. See also VF_min, VF_absmax, VF_runmin, VF_minind, VCF_absminReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_absminind VD_absminind VE_absminind │ │ VCF_absminind VCD_absminind VCE_absminind │ └────────────────────────────────────────────────────────────────────────────┘ Function Smallest absolute value and the index of its first occurrence. Syntax #include <VFstd.h> float VF_absminind( ui *Ind, fVector X, ui size ); (similarly VD_, VE_) float VCF_absminind( ui *Ind, cfVector X, ui size ); (similarly VCD_, VCE_) Description The absolute values of all elements of a vector are compared and the smallest returned. For complex numbers, the magnitudes of the elements are compared and the smallest returned. The index of this minimum is stored at the address given by Ind. In case of more than one element with the same minimum value, the lowest index is chosen. Error handling none Return value minimum absolute value encountered. See also VF_minind, VF_absmin, VF_runmin, VF_maxind, VCF_absminReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_absminReIm VCD_absminReIm VCE_absminReIm │ └────────────────────────────────────────────────────────────────────────────┘ Function Separate determination of the smallest absolute values of the real and imaginary parts occurring in a complex vector. Syntax #include <VCFstd.h> fComplex VCF_absminReIm( cfVector X, ui size ); (similarly( VCD_, VCE_) Description The absolute values of the real parts of all vector elements are compared with each other and the smallest one is returned as the real part of the result. Similarly, the absolute values of all the imaginary parts are compared with each other and the smallest one is returned as the imaginary part of the result. Generally, the result is made up from different elements of the vector. Error handling none Return value Smallest absolute real and imaginary parts, combined into one complex number. See also VCF_minReIm, VCF_absmaxReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_acos VD_acos VE_acos │ │ VCF_acos VCD_acos VCE_acos │ │ VFx_acos VDx_acos VEx_acos │ │ VCFx_acos VCDx_acos VCEx_acos │ └────────────────────────────────────────────────────────────────────────────┘ Function arcus cosinus function Syntax #include <VFmath.h> int VF_acos( fVector Y, fVector X, ui size ); int VFx_acos( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = arccos ( Xi ) expanded versions: Yi = C * arccos (A*Xi + B ) Error handling Real versions: DOMAIN errors occur for arguments outside the range -1 <= Xi <= +1; the default result is NAN ("not-a- number"). The complex versions should be error-proof as long as the parameter C in the expanded versions is not already near the OVERFLOW limit; this very rare error is neither detected nor handled. Return value 0, if no error occurred, otherwise non-zero. See also VF_cos, VF_asin, VF_atan, acos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_addC VD_addC VE_addC │ │ VCF_addC VCD_addC VCE_addC │ │ VCF_addReC VCD_addReC VCE_addReC │ │ VI_addC VSI_addC VLI_addC VQI_addC │ │ VU_addC VUS_addC VUL_addC VUI_addC │ └────────────────────────────────────────────────────────────────────────────┘ Function Add a constant to a vector Syntax #include <VFmath.h> void VF_addC( fVector Y, fVector X, ui size, float C); (similarly VD_, VI_, etc.) void VCF_addC( cfVector Y, cfVector X, ui size, fComplex C ); void VCF_addReC( cfVector Y, cfVector X, ui size, float CRe ); (similarly VCD_, VCE_) Description Yi = Xi + C The complex floating-point versions exist in two variants, one for complex constants C, the other for real-valued constants CRe added to the complex vector. Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_addV, VF_subC, VF_mulC, VF_divC, VF_visC, VF_redC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_addV VD_addV VE_addV │ │ VCF_addV VCD_addV VCE_addV │ │ VCF_addReV VCD_addReV VCE_addReV │ │ VFs_addV VDs_addV VEs_addV │ │ VFx_addV VDx_addV VEx_addV │ │ VCFx_addV VCDx_addV VCEx_addV │ │ VCFx_addReV VCDx_addReV VCEx_addReV │ │ VI_addV VSI_addV VLI_addV VQI_addV │ │ VU_addV VUS_addV VUL_addV VUI_addV │ └────────────────────────────────────────────────────────────────────────────┘ Function Add two vectors Syntax #include <VFmath.h> void VF_addV( fVector Z, fVector X, fVector Y, ui size ); void VFs_addV( fVector Z, fVector X, fVector Y, ui size, float C ); void VFx_addV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); (similarly VD_, VDx_, VE_, VEx_, VI_, etc.) void VCF_addV( cfVector Z, cfVector X, cfVector Y, ui size ); void VCF_addReV( cfVector Z, cfVector X, fVector Y, ui size ); void VCFx_addV( cfVector Z, cfVector X, cfVector Y, ui size, fComplex A, fComplex B ); void VCFx_addReV( cfVector Z, cfVector X, fVector Y, ui size, fComplex A, fComplex B ); (similarly VCD_, VCDx_, VCE_, VCEx_) Description normal versions: Zi = Xi + Yi scaled versions: Zi = C * (Xi + Yi) expanded versions: Zi = (A * Xi + B) + Yi The complex floating-point versions exist in two variants. In the first variant (e.g.VCF_addV, VCFx_addV), X, Y, and Z are all complex; in the second variant, Y is real-valued (e.g., VCF_addReV - "add a real vector"). Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_addC, VF_subV, VF_mulV, VF_divV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VI_and VSI_and VLI_and VQI_and │ │ VU_and VUS_and VUL_and VUI_and │ └────────────────────────────────────────────────────────────────────────────┘ Function Bit-wise AND operation. Syntax #include <VImath.h> void VI_and( iVector Y, iVector X, ui size, int C ); (similarly all other functions of this family) Description Yi = (Xi) & C The bit-wise AND operation is performed on each element Xi with the bit-mask given by C. A bit is 1 in Yi, if it was 1 both in Xi and in C, and 0 otherwise. Perhaps the most useful application of this family of functions is the fast "modulo" operation on unsigned or positive numbers with the modulus being an integer power of 2. For example, a modulo division by 64 is performed by VU_and( Y, X, size, 64-1 ); Error handling none Return value none See also VI_not, VI_or, VI_xor ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_arg VCD_arg VCE_arg │ └────────────────────────────────────────────────────────────────────────────┘ Function Argument (angle in polar coordinates). Implemented as a macro that calls VF_CtoArg, VD_CtoArg, VE_CtoArg, resp. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_asin VD_asin VE_asin │ │ VCF_asin VCD_asin VCE_asin │ │ VFx_asin VDx_asin VEx_asin │ │ VCFx_asin VCDx_asin VCEx_asin │ └────────────────────────────────────────────────────────────────────────────┘ Function arcus sinus function Syntax #include <VFmath.h> int VF_asin( fVector Y, fVector X, ui size ); int VFx_asin( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = arcsin ( Xi ) expanded versions: Yi = C * arcsin (A*Xi + B ) Error handling Real versions: DOMAIN errors occur for arguments outside the range -1 <= Xi <= +1; the default result is NAN ("not-a- number"). The complex versions should be error-proof as long as the parameter C in the expanded versions is not already near the OVERFLOW limit; this very rare error is either detected nor handled. Return value 0, if no error occurred, otherwise non-zero. See also VF_sin, VF_acos, VF_atan, asin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_atan VD_atan VE_atan │ │ VCF_atan VCD_atan VCE_atan │ │ VFx_atan VDx_atan VEx_atan │ │ VCFx_atan VCDx_atan VCEx_atan │ └────────────────────────────────────────────────────────────────────────────┘ Function arcus tangens function Syntax #include <VFmath.h> int VF_atan( fVector Y, fVector X, ui size ); int VFx_atan( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = arctan ( Xi ) expanded versions: Yi = C * arctan (A*Xi + B ) Error handling The real versions should be error-proof as long as the parameter C in the expanded versions is not already near the OVERFLOW limit; this very rare error is neither detected nor handled. In the complex versions, the result for an argument of {0, -1} is set to {0, -Pi} without notice (and without the program crash resulting in Borland C++ from calling the complex atan with this argument). Return value always 0. See also VF_tan, VF_asin, VF_acos, VF_atan2, atan, atan2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_atan2 VD_atan2 VE_atan2 │ │ VFx_atan2 VDx_atan2 VEx_atan2 │ └────────────────────────────────────────────────────────────────────────────┘ Function arcus tangens function of quotients Syntax #include <VFmath.h> int VF_atan2( fVector Z, fVector X, fVector Y, ui size ); int VFx_atan2( fVector Z, fVector X, fVector Y, ui size, float A, float B, float C ); Description normal versions: Zi = arctan( Yi / Xi ) expanded versions: Zi = C * arctan( Yi / (A*Xi+B) ) From Cartesian X - Y- coordinates, the angle of the corresponding polar coordinates is calculated. Be careful: in comparison to the ANSI C function atan2, the ordering of the parameters X and Y is reversed. Error handling If Xi and Yi are both zero, a DOMAIN error results with the default result NAN ("not-a-number"); this error is handled by _matherr and _matherrl with Xi and Yi as e->x and e->y. Return value 0, if no error occurred, otherwise non-zero. See also VF_tan, VF_asin, VF_acos, VF_atan, atan, atan2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_autocorr VD_autocorr VE_autocorr │ └────────────────────────────────────────────────────────────────────────────┘ Function autocorrelation function Syntax #include <VFstd.h> void VF_autocorr( fVector Y, fVector X, ui size ); Description The autocorrelation function (ACF) of X is calculated and stored in Y in wrap-around order: Y[0] to Y[size/2-1] contain the ACF for zero and positive lags. Beginning with the most negative lag in Y[size/2+1], the elements up to Y[size-1] contain the ACF for negative lags. Since this function assumes X to be periodic, the ACF for the most positive lag is identical to the ACF for the most negative lag. This element is stored as Y[size/2]. To get the ACF into normal order, you may call VF_rotate( Y, Y, size, size/2 ); After that, the zero point is at the position size/2. In case X is non-periodic, you should avoid end effects by the methods described in connection with VF_convolve. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Error handling If size is not a power of 2, VF_FFT (on which VF_autocorr is based) complains "Size must be an integer power of 2" and the program is aborted. Return value none See also VF_FFT, VF_convolve, VF_xcorr, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_autoPlot VCD_autoPlot VCE_autoPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Automatic plot of a complex vector into a Cartesian complex plane. Syntax #include <Vgraph.h> void VCF_autoPlot( cfVector X, ui size, unsigned form, COLORREF color ); Description A Cartesian complex plane is drawn with the axes automatically scaled and the vector X plotted into it. For a description of the parameters form and color, see VF_xyAutoPlot. The plotting routines have to be initialized by V_initGraph or V_initPlot prior to calling VCF_autoPlot. Error handling none Return value none See also VCF_2AutoPlot, VCF_dataPlot, VF_xyAutoPlot, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_2AutoPlot VCD_2AutoPlot VCE_2AutoPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Automatic plot of two complex vectors into a Cartesian complex plane. Syntax #include <Vgraph.h> void VCF_2AutoPlot( cfVector X1, ui size1, unsigned form1, COLORREF color1, cfVector X2, ui size2, unsigned form2, COLORREF color2 ); Description A Cartesian complex plane is drawn with the axes automatically scaled and the vectors X1 and X2 plotted into it. For a description of the parameters form1, form2, color1, and color2, see VF_xyAutoPlot. The plotting routines have to be initialized by V_initGraph or V_initPlot prior to calling VCF_2AutoPlot. Error handling none Return value none See also VCF_autoPlot, VCF_dataPlot, VF_xyAutoPlot, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_avdevC VD_avdevC VE_avdevC │ └────────────────────────────────────────────────────────────────────────────┘ Function average deviation from a preset value Syntax #include <VFstd.h> float VF_avdevC( fVector X, ui size, float C ); Description avdevC = 1/size * sum( │Xi - C│ ) The average of the absolute deviation of each element of X from C is calculated and returned. Error handling none Return value average deviation. See also VF_ssq, VF_ssqdevC, VF_avdevV, VF_sumdevC, VF_chiabs ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_avdevV VD_avdevV VE_avdevV │ └────────────────────────────────────────────────────────────────────────────┘ Function average deviation of the elements of one vector from the corresponding elements of another vector. Syntax #include <VFstd.h> float VF_avdevV( fVector X, fVector Y, ui size ); Description avdevV = 1/size * sum( │Xi - Yi│ ) The average of the absolute deviation of each element of X from the corresponding element of Y is calculated. Error handling none Return value average deviation. See also VF_ssq, VF_ssqdevV, VF_avdevC, VF_sumdevV, VF_chiabs ┌────────────────────────────────────────────────────────────────────────────┐ │ V_CDtoCF V_CDtoCE │ │ V_CEtoCF V_CEtoCD │ │ V_CFtoCD V_CFtoCE │ └────────────────────────────────────────────────────────────────────────────┘ Function Data type conversions. See V_FtoD. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ceil VD_ceil VE_ceil │ │ VF_ceiltoI VD_ceiltoI VE_ceiltoI │ │ VF_ceiltoSI VD_ceiltoSI VE_ceiltoSI │ │ VF_ceiltoLI VD_ceiltoLI VE_ceiltoLI │ │ VF_ceiltoQI VD_ceiltoQI VE_ceiltoQI │ │ VF_ceiltoU VD_ceiltoU VE_ceiltoU │ │ VF_ceiltoUS VD_ceiltoUS VE_ceiltoUS │ │ VF_ceiltoUL VD_ceiltoUL VE_ceiltoUL │ │ VF_ceiltoUI VD_ceiltoUI VE_ceiltoUI │ └────────────────────────────────────────────────────────────────────────────┘ Function Rounding to the next whole number that is greater or equal. Syntax #include <VFmath.h> int VF_ceil( fVector Y, fVector X, ui size ); int VF_ceiltoI( iVector Y, fVector X, ui size ); int VF_ceiltoLI( liVector Y, fVector X, ui size ); (similarly all other functions of this family) Description Each element of X is rounded to the nearest whole number that is greater than or equal to the input number and the result stored in Y. The functions VF_ceiltoI, VF_ceiltoLI, VF_ceiltoU etc. convert the result into the various integer data types (in the cases mentioned, to int, long int, and unsigned, resp.). Error handling OVERFLOW errors are handled by setting the result to the extreme value possible. Negative numbers in the versions VF_ceiltoU, VF_ceiltoUS, VF_ceiltoUL, and VF_ceiltoUI lead to DOMAIN errors; they are handled by setting the result to 0. Return value 0, if no error occurred, otherwise non-zero. See also ceil, floor, VF_round, VF_floor, VF_chop, VF_trunc ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_chiabs VD_chiabs VE_chiabs │ └────────────────────────────────────────────────────────────────────────────┘ Function Absolute-value analogue of the chi-square merit function. Syntax #include <VFstd.h> float VF_chiabs( fVector X, fVector Y, fVector Wt, ui size ); Description chiabs = sum( weighti * |Xi - Yi| ). The chiabs function is a "robust" replacement for the chi-square merit function. It is used to judge the quality of a fit in the presence of outlier points. The chiabs function is disturbed by outlier points to a lesser degree than the chi-square function. Error handling none Return value chiabs merit function. See also VF_chi2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_chi2 VD_chi2 VE_chi2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Chi-square merit function. Syntax #include <VFstd.h> float VF_chi2( fVector X, fVector Y, fVector InvVar, ui size ); Description chi² = sum( 1/sigmai² * (Xi - Yi)² ). The chi-square merit function is most often used to judge the quality of a fit. One vector (either X or Y) represents experimental values that are obtained with individual standard deviations sigmai, the other contains the values predicted on the basis of a theory or a model. If the experimental data are "normally" distributed, and if sigma is the correct measure for the quality of these data, then chi² is a measure for the quality of the fit. Rather than the standard deviations themselves, the routine needs the inverse of their squares (i.e., the inverse of the variances) to be passed as the vector InvVar. Error handling none Return value chi² merit function. See also VF_meanwW, VF_varianceVwW, VF_varianceV, VF_varianceCwW, VF_chiabs, VF_square, VF_inv, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_chop VD_chop VE_chop │ │ VF_choptoI VD_choptoI VE_choptoI │ │ VF_choptoSI VD_choptoSI VE_choptoSI │ │ VF_choptoLI VD_choptoLI VE_choptoLI │ │ VF_choptoQI VD_choptoQI VE_choptoQI │ │ VF_choptoU VD_choptoU VE_choptoU │ │ VF_choptoUS VD_choptoUS VE_choptoUS │ │ VF_choptoUL VD_choptoUL VE_choptoUL │ │ VF_choptoUI VD_choptoUI VE_choptoUI │ └────────────────────────────────────────────────────────────────────────────┘ Function "Chopping" towards zero. Syntax #include <VFmath.h> int VF_chop( fVector Y, fVector X, ui size ); int VF_choptoI( iVector Y, fVector X, ui size ); int VF_choptoLI( liVector Y, fVector X, ui size ); (similarly all other functions of this family) Description Each element of X is rounded to an integer number by "chopping off" the fractional part. For example, -3.9 yields -3, and +3.9 yields +3. The result is stored in Y. The functions VF_choptoI, VF_choptoLI, etc. convert the result into the various integer data types. Error handling OVERFLOW errors are handled by setting the result to the extreme value possible. Negative numbers in the versions VF_choptoU, VF_choptoUS, VF_choptoUL, and VF_choptoUI lead to DOMAIN errors; they are handled by setting the result to 0. Return value 0, if no error occurred, otherwise non-zero. See also ceil, floor, VF_round, VF_floor, VF_ceil ┌────────────────────────────────────────────────────────────────────────────┐ │ V_closeErrorEventFile │ └────────────────────────────────────────────────────────────────────────────┘ Function Restore default printing of error messages into stderr. Syntax #include <VecLib.h> void V_closeErrorEventFile( void ); Description After error messages have been redirected into an event file by V_setErrorEventFile, the default is restored by V_closeErrorEventFile and any further messages will be printed into stderr which normally is the screen (see Chapter 5.5). Both of thess functions will not be included in versions of VectorLib for compilers that do already offer the possibility of printing error messages simultaneously to the screen and to an event file. Error handling none Return value none See also V_noteError, V_setErrorEventFile, _matherr ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cmp0 VD_cmp0 VE_cmp0 │ └────────────────────────────────────────────────────────────────────────────┘ Function Compares each element of a vector with 0 (signum function). Syntax #include <VFmath.h> void VF_cmp0( fVector Y, fVector X, ui size ); Description Each element of X is compared with 0 and the result of the comparison stored in Y: Yi = 1.0, if Xi > 0 Yi = 0.0, if Xi = 0 Yi = -1.0, if Xi < 0. This function may also be called under its synonym VF_sgn. Error handling none Return value none See also VF_cmp_..., VF_cmpC, VF_cmpV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cmpC VD_cmpC VE_cmpC │ └────────────────────────────────────────────────────────────────────────────┘ Function Compares each element of a vector with a constant. Syntax #include <VFmath.h> void VF_cmpC( fVector Y, fVector X, ui size, float C ); Description Each element of X is compared with C and the result of the comparison stored in Y: Yi = 1.0, if Xi > C Yi = 0.0, if Xi = C Yi = -1.0, if Xi < C To compare with C=0, use more efficiently the function VF_cmp0. Error handling none Return value none See also VF_cmp_..., VF_cmp0, VF_cmpV, VF_iselementC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cmpV VD_cmpV VE_cmpV │ └────────────────────────────────────────────────────────────────────────────┘ Function Compares each element of a vector with the corresponding element of another vector. Syntax #include <VFmath.h> void VF_cmpV( fVector Z, fVector X, fVector Y, ui size ); Description Each element of X is compared with the corresponding element of Y and the result of the comparison stored in Z: Zi = 1.0, if Xi > Yi Zi = 0.0, if Xi = Yi Zi = -1.0, if Xi < Yi. Error handling none Return value none See also VF_cmp_..., VF_cmp0, VF_cmpV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cmp_... VD_cmp_... VE_cmp_... │ │ VCF_cmp_... VCD_cmp_... VCE_cmp_... │ └────────────────────────────────────────────────────────────────────────────┘ Function Comparisons Syntax #include <VFmath.h> ui VF_cmp_eq0( fVector Y, fVector X, ui size ); ui VF_cmp_ne0( fVector Y, fVector X, ui size ); ui VF_cmp_gt0( fVector Y, fVector X, ui size ); ui VF_cmp_ge0( fVector Y, fVector X, ui size ); ui VF_cmp_lt0( fVector Y, fVector X , ui size ); ui VF_cmp_le0( fVector Y, fVector X, ui size ); ui VF_cmp_eqC( fVector Y, fVector X, ui size, float C ); ... (similarly: VF_cmp_neC, VF_cmp_gtC, VF_cmp_geC, VF_cmp_ltC, VF_cmp_leC) ui VF_cmp_eqV( fVector Z, fVector X, fVector Y, ui size); ... (similarly: VF_cmp_neV, VF_cmp_gtV, VF_cmp_geV, VF_cmp_ltV, VF_cmp_leV) ui VF_cmp_eq0ind( uiVector Ind, fVector X, ui size ); ... (similarly: VF_cmp_ne0ind, VF_cmp_gt0ind, VF_cmp_ge0ind, VF_cmp_lt0ind, VF_cmp_le0ind) ui VF_cmp_eqCind( uiVector Ind, fVector X, ui size, float C ); ... (similarly: VF_cmp_neCind, VF_cmp_gtCind, VF_cmp_geCind, VF_cmp_ltCind, VF_cmp_leCind) ui VF_cmp_eqVind( uiVector Ind, fVector X, fVector Y, ui size ); ... (similarly: VF_cmp_neVind, VF_cmp_gtVind, VF_cmp_geVind, VF_cmp_ltVind, VF_cmp_leVind) (similarly VD_ and VE_ versions) ui VCF_cmp_eq0( cfVector Y, cfVector X, ui size ); ui VCF_cmp_ne0( cfVector Y, cfVector X, ui size ); ui VCF_cmp_eqC( cfVector Y, cfVector X, ui size, fComplex C ); ui VCF_cmp_neC( cfVector Y, cfVector X, ui size, fComplex C ); ui VCF_cmp_eqV( cfVector Z, cfVector X, cfVector Y, ui size ); ui VCF_cmp_neV( cfVector Z, cfVector X, cfVector Y, ui size ); ui VCF_cmp_eq0ind( uiVector Ind, cfVector X, ui size ); ui VCF_cmp_ne0ind( uiVector Ind, cfVector X, ui size ); ui VCF_cmp_eqCind( uiVector Ind, cfVector X, ui size, fComplex C ); ui VCF_cmp_neCind( uiVector Ind, cfVector X, ui size, fComplex C ); ui VCF_cmp_eqVind( uiVector Ind, cfVector X, cfVector Y, ui size ); ui VCF_cmp_neVind( uiVector Ind, cfVector X, cfVector Y, ui size ); (similarly VCD_ and VCE_ versions) Description Each element of X is compared with either 0, or a constant C, or the corresponding element of another vector, Y. The conditions to be tested are denoted by two letters as in ASSEMBLER or FORTRAN: "eq" ("equal"): True, if Xi = 0 (C, Yi, resp.) "ne" ("not equal"): True, if Xi != 0 (C, Yi, resp.) "gt" ("gteater than"): True, if Xi > 0 (C, Yi, resp.) "ge" ("greater or equal"): True, if Xi >= 0 (C, Yi, resp.) "lt" ("less than"): True, if Xi < 0 (C, Yi, resp.) "le" ("less or equal"): True, if Xi <= 0 (C, Yi, resp.). For complex numbers, only the testing for equality ("eq") or inequality ("ne") makes sense and is available. There are two different ways how the result of the comparison is treated. The result for each element of X is either stored as 1.0 for TRUE and 0.0 for FALSE in a vector of a floating- point data type (with the imaginary part in the complex versions always set to 0), or the indices of the elements for which the result is TRUE are stored in an index vector; the latter is the case in the functions with the suffix "ind" as the last part of their names, like in VF_cmp_neCind. In any case, the number of TRUE results encountered is returned by the function. The index-finding variant is especially useful to extract the elements for which the condition is TRUE into a sub-vector by VF_indpick; be sure to check that the return value nTrue is non-zero if you wish to do that (remember that the parameter size for any of the functions of this VectorLib library must be non-zero!). Error handling none Return value number of elements for which the condition was found to be TRUE. See also VF_cmp0, VF_cmpC, VF_cmpV, VF_indpick, VF_iselementC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_comb VD_comb VE_comb │ └────────────────────────────────────────────────────────────────────────────┘ Function Initializes a vector with a comb function. Syntax #include <VFstd.h> void VF_comb( fVector X, ui size, ui spac, float C ); Description Xi = C, i = 0, 1*spac, 2*spac,... Xi = 0, otherwise Error handling If the spacing spac of the comb exceeds size, an error message "Invalid parameter(s)" is displayed and the program aborted. Return value none See also VF_equ1, VF_equ0, VF_equC ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_complex VCD_complex VCE_complex │ └────────────────────────────────────────────────────────────────────────────┘ Function Constructs a Cartesian complex vector from its real and imaginary parts. Implemented as a macro that calls VF_ReImtoC, VD_ReImtoC, VE_ReImtoC, resp. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_conj VCD_conj VCE_conj │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the complex conjugate of a vector. Syntax #include <VCFmath.h> int VCF_conj( cfVector Y, cfVector X, ui size ); Description Re(Yi) = Re(Xi) Im(Yi) = -Im(Xi) Error handling none Return value always 0 See also VCF_neg, VF_abs ┌────────────────────────────────────────────────────────────────────────────┐ │ V_continuePlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Get back into the last viewport used for plotting Syntax #include <Vgraph.h> void V_continuePlot( void ); Description If one wants to add new DataPlots to an existing coordinate system after one has already defined a new viewport (e.g., for text output), this function takes one back to the most recently used coordinate system. Error handling none Return value none See also V_getCoordSystem, V_setCoordSystem, V_setPlotRegion ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_convolve VD_convolve VE_convolve │ └────────────────────────────────────────────────────────────────────────────┘ Function Calculates the convolution of a vector with a response function. Syntax #include <VFstd.h> void VF_convolve( fVector Y, fVector Flt, fVector X, fVector Rsp, ui size ); Description The convolution of X with the response function Rsp is calculated and stored in Y. A filter Flt is also calculated. If more than one vector is to be convolved with the same Rsp, use VF_convolve only once and use VF_filter for the other vectors. The response has to be stored in Rsp in wrap-around order: the response for zero and positive times (or whatever the independent variable is) is stored in Rsp[0] to Rsp[size/2] and the response for negative times (beginning with the most negative time) in Rsp[size/2+1] to Rsp[size-1]. You may wish to use VF_rotate or VF_reflect to achieve this wrap-around order and to construct the response vector. Notice that Rsp has to be of the same size as X. The result of the convolution appears scaled with the sum of all elements of Rsp. Normally, therefore, Rsp should be normalized to 1.0. X, Y, Rsp, and Flt must all be of the same size, which has to be an integer power of 2. X may be overwritten by Y, Rsp may be overwritten by Flt, but X and Flt as well as Y and Rsp have to be distinct from each other. The treatment of round-off errors in the construction of Flt may be modified by VF_setRspEdit. Example VF_ramp( Time, 1024, 0.0, 1.0 ); VF_Gauss( Rsp, Time, 513, 10.0, 0.0, 1.0 ); /* Response function for zero and positive times */ VF_reflect( Rsp+1, 1023 ); /* ... and for negative times */ VF_divC( Rsp, Rsp, 1024, VF_sum( Rsp, 1024 ) ); /* Normalisation of Rsp */ VF_convolve( X, Rsp, X, Rsp, 1024 ); /* Convolution; X is overwritten by the desired result and Rsp is overwritten by the frequency filter */ VF_filter( Y, Y, Rsp, 1024 ); /* Next convolution: instead of another call to VF_convolve, Y is filtered using the frequency filter just obtained */ Mathematically, this convolution is based on the assumption that X is periodic; it still works well if X is non-periodic but converges on both ends to the same value X[0] = X[size-1]. If that is not the case, the first and the last elements of Y are spoiled by "wrap-around" from elements on the other side. Extrapolate X on both sides in order to imbed the original X in a larger vector, if wrap-around is a problem. The minimum number of elements to be added equals half the width of the response function. (In the case of an asymmetric response function, it is the broader wing that counts.) After con- volving the larger vector with the response function, it will be the dummy elements just added which become spoiled by wrap-around. Those elements of the result vector which correspond to the original X will represent the desired convolution of X with Rsp. If X is smoothly converging on both sides to different values, it is not necessary to employ the procedure just described. Rather, the difference between the end points may be regarded as a linear trend. In this case, remove the trend, convolve the resultant vector and add the trend to the result. Example d = (X[size-1] - X[0]) / (size-1); VF_ramp( Trend, size, 0.0, d ); VF_subV( Y, X, Trend, size ); VF_convolve( Y, Flt, Y, Rsp, size ); VF_addV( Y, Y, Trend, size ); You might notice that Flt is declared as fVector rather than cfVector, although the information stored in Flt consists of complex numbers. The reason is that these numbers are stored in the packed complex format (as described for VF_FFT) which is used only in connection with Fourier-Transform operations of real vectors. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Error handling If size is not a power of 2, VF_FFT (on which VF_convolve is based) complains "Size must be an integer power of 2" and the program is aborted. Return value none See also VF_filter, VF_deconvolve, VF_FFT, VF_autocorr, VF_xcorr, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_corrcoeff VD_corrcoeff VE_corrcoeff │ └────────────────────────────────────────────────────────────────────────────┘ Function Linear correlation coefficient between two distributions Syntax #include <VFstd.h> float VF_corrcoeff( fVector X, fVector Y, ui size, float Xmean, float Ymean ); Description The linear correlation coefficient ("Pearson's r") takes on values between -1.0 and +1.0. The mean values of both distributions must be known. They are passed to VF_corrcoeff as the parameters Xmean and Ymean. Example r = VF_corrcoeff( X, Y, n, VF_mean( X, n ), VF_mean( Y, n ) ); Error handling none Return value linear correlation coefficient r See also VF_mean, VF_varianceV, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cos VD_cos VE_cos │ │ VCF_cos VCD_cos VCE_cos │ │ VFx_cos VDx_cos VEx_cos │ │ VCFx_cos VCDx_cos VCEx_cos │ └────────────────────────────────────────────────────────────────────────────┘ Function Cosine function Syntax #include <VFmath.h> int VF_cos( fVector Y, fVector X, ui size ); int VFx_cos( fVector Y, fVector X, ui size, float A, float B, float C ); Beschreibung normal versions: Yi = cos ( Xi ) expanded versions: Yi = C * cos (A*Xi + B ) For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as rational multiples of Pi, it is better to use VF_cosrpi than VF_cos. Error handling Precision errors in the real-value functions lead to a default result of 1.0 (as if the input were 0.0) and to a non-zero return value, but are otherwise ignored; _matherr is not called. OVERFLOW errors can only occur in the complex versions and lead to a result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_cos2, VF_cosrpi, VF_sin, VF_cosh, VF_acos, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cos2 VD_cos2 VE_cos2 │ │ VFx_cos2 VDx_cos2 VEx_cos2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the cosine function Syntax #include <VFmath.h> int VF_cos2( fVector Y, fVector X, ui size ); int VFx_cos2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = cos²( Xi ) expanded versions: Yi = C * cos²(A*Xi + B ) Calculating the squared trigonometric functions directly is faster and sometimes more accurate than first calculating the trigonometric function itself and squaring it afterwards. Error handling Precision errors lead to a default result of 1.0 (as if the input were 0.0) and a non-zero return value, but are otherwise ignored; _matherr is not called. OVERFLOW errors can only occur in the complex versions and lead to a result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_cos, VF_cosrpi, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosec VD_cosec VE_cosec │ │ VFx_cosec VDx_cosec VEx_cosec │ └────────────────────────────────────────────────────────────────────────────┘ Function Cosecant function Syntax #include <VFmath.h> int VF_cosec( fVector Y, fVector X, ui size ); int VFx_cosec( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = cosec ( Xi ) = 1.0 / sin ( Xi ) expanded versions: Yi = C * cosec ( A*Xi + B ) The cosecant is defined as the inverse of the sine (not to be mistaken for the arcus function arcsin!) For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as rational multiples of Pi, it is better to use VF_cosecrpi than VF_cosec. Error handling For TLOSS precision errors, the default result is arbitrarily set to 1.0 (as an exception from the general rule which would require the result to be the mean of the results for +0 and -0. This would be 0.0. However, zero is not a valid result for the cosecant function). For SING and OVERFLOW errors, the default result is ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_cosec2, VF_cosecrpi, VF_sin, VF_cosech, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosec2 VD_cosec2 VE_cosec2 │ │ VFx_cosec2 VDx_cosec2 VEx_cosec2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the cosecant function Syntax #include <VFmath.h> int VF_cosec2( fVector Y, fVector X, ui size ); int VFx_cosec2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = cosec² ( Xi ) expanded versions: Yi = C * cosec² ( A*Xi + B ) Calculating the squared trigonometric functions directly is faster and sometimes more accurate than first calculating the trigonometric function itself and squaring it afterwards. Error handling For SING, OVERFLOW, and TLOSS errors, the default result is ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_cosec, VF_cosecrpi, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosech VD_cosech VE_cosech │ │ VFx_cosech VDx_cosech VEx_cosech │ └────────────────────────────────────────────────────────────────────────────┘ Function Hyperbolic cosecant function Syntax #include <VFmath.h> int VF_cosech( fVector Y, fVector X, ui size ); int VFx_cosech( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = cosech ( Xi ) expanded versions: Yi = C * cosech ( A*Xi+B ) Error handling SING errors lead to a default result of 0 (mean of +HUGE_VAL and -HUGE_VAL); OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_sinh, VF_exp, sinh ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosecrpi VD_cosecrpi VE_cosecrpi │ │ VF_cosecrpi2 VD_cosecrpi2 VE_cosecrpi2 │ │ VF_cosecrpi3 VD_cosecrpi3 VE_cosecrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Cosecant function of fractional multiples of Pi Syntax #include <VFmath.h> int VF_cosecrpi( fVector Y, iVector P, ui size, int q ); int VF_cosecrpi2( fVector Y, iVector P, ui size, int q ); int VF_cosecrpi3( fVector Y, iVector P, ui size, int q ); Description Yi = cosec( (P[i] / q) * Pi ) The cosecant of fractional multiples of Pi is calculated. There are three versions: VF_cosecrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_cosecrpi2 should be used which is a highly optimized version using a look-up table. If q is a multiple of 3, VF_cosecrpi3 should be used. VF_cosecrpi2 and VF_cosecrpi3 work also with q values they are not optimized for; in this case, however, memory space is wasted for the tables. Error handling SING errors occur if P[i] / q is exactly an integer number; the default result is 0.0 (which is the mean of +HUGE_VAL and -HUGE_VAL; in contrast to VF_cosec, 0.0 is chosen irrespective of the fact that it is not a valid result of the cosecant function); q must be non-zero; this is, however, not tested for. Return value 0, if no error occurred, otherwise non-zero. See also VF_cosec, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosectab2 VD_cosectab2 VE_cosectab2 │ │ VF_cosectab3 VD_cosectab3 VE_cosectab3 │ └────────────────────────────────────────────────────────────────────────────┘ Table of cosecant values for arguments between 0 and Pi/2. Syntax #include <xmath.h> extern float VF_cosectab2[ VF_tabsz2+1 ]; extern double VD_cosectab2[ VD_tabsz2+1 ]; extern extended VE_cosectab2[ VE_tabsz2+1 ]; extern float VF_cosectab3[ VF_tabsz3+1 ]; extern double VD_cosectab3[ VD_tabsz3+1 ]; extern extended VE_cosectab3[ VE_tabsz3+1 ]; Description VF_cosectab2[ i ] = cosec( i/(2*VF_tabsz2) * Pi ), i=0,...,VF_tabsz2-1 VF_cosectab3[ i ] = cosec ( i/(2*VF_tabsz3) * Pi ), i=0,...,VF_tabsz3-1 VF_cosectab2[ VF_tabsz2 ] = VF_cosectab3[ VF_tabsz3 ] = 0 These look-up tables of cosecant values for arguments between 0 and Pi/2 are used by VF_cosecrpi2 and the other functions of that family and are also available to the user. Since the cosecant of Pi/2 is not defined, zero is stored at its place. The symbols VF_tabsz2 etc., denoting the size of the tables, are defined in <xmath.h>. See also VF_cosecrpi2, VF_tantab2, VF_sintab2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosh VD_cosh VE_cosh │ │ VCF_cosh VCD_cosh VCE_cosh │ │ VFx_cosh VDx_cosh VEx_cosh │ │ VCFx_cosh VCDx_cosh VCEx_cosh │ └────────────────────────────────────────────────────────────────────────────┘ Function Hyperbolic cosine function Syntax #include <VFmath.h> int VF_cosh( fVector Y, fVector X, ui size ); int VFx_cosh( fVector Y, fVector X, ui size, float A, float B, float C ); int VCF_cosh( cfVector Y, cfVector X, ui size ); int VCFx_cosh( cfVector Y, cfVector X, ui size, fComplex A, fComplex B, fComplex C ); Description normal versions: Yi = cosh ( Xi ) expanded versions: Yi = C * cosh ( A*Xi+B ) Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_sinh, VF_exp, cosh ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cosrpi VD_cosrpi VE_cosrpi │ │ VF_cosrpi2 VD_cosrpi2 VE_cosrpi2 │ │ VF_cosrpi3 VD_cosrpi3 VE_cosrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Cosine function of fractional multiples of Pi Syntax #include <VFmath.h> int VF_cosrpi( fVector Y, iVector P, ui size, int q ); int VF_cosrpi2( fVector Y, iVector P, ui size, int q ); int VF_cosrpi3( fVector Y, iVector P, ui size, int q ); Description Yi = cos( (P[i] / q) * Pi ) The cosine of fractional multiples of Pi is calculated. There are three versions: VF_cosrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_cosrpi2 should be used which is a highly optimized version reading the results from a look-up table, if possible. If q is a multiple of 3, VF_cosrpi3 should be used. VF_cosrpi3 offers a convenient way to use degrees instead of radians; if, for example, q is 180, the unit of the elements of P is "degree". VF_cosrpi2 and VF_cosrpi3 work also with q values they are not optimized for; in this case, however, memory space is wasted for the tables. Error handling These functions are error-proof, as long as q != 0. Return value always 0 See also VF_cos, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cot VD_cot VE_cot │ │ VFx_cot VDx_cot VEx_cot │ └────────────────────────────────────────────────────────────────────────────┘ Function Cotangent function Syntax #include <VFmath.h> int VF_cot( fVector Y, fVector X, ui size ); int VFx_cot( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = cot ( Xi ) expanded versions: Yi = C * cot ( A*Xi+B ) The cotangent is defined as the inverse of the tangent (not to be mistaken for the arcus function arctan!) For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as rational multiples of Pi, it is better to use VF_cotrpi than VF_cot. Error handling For TLOSS precision errors, the default result is 0.0 (which is the mean of +HUGE_VAL and -HUGE_VAL); for SING and OVERFLOW errors, the default result is ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_cot2, VF_cotrpi, VF_coth, VF_atan, VF_atan2, tan ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cot2 VD_cot2 VE_cot2 │ │ VFx_cot2 VDx_cot2 VEx_cot2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the cotangent function Syntax #include <VFmath.h> int VF_cot2( fVector Y, fVector X, ui size ); int VFx_cot2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = cot²( Xi ) expanded versions: Yi = C * cot²( A*Xi+B ) Calculating the squared trigonometric functions directly is faster and sometimes more accurate than first calculating the trigonometric function itself and squaring it afterwards. Error handling For SING, OVERFLOW and TLOSS errors, the default result is +HUGE_VAL (multiplied by the sign of C in the expanded versions). Return value 0, if no error occurred, otherwise non-zero. See also VF_cot, VF_cotrpi, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_coth VD_coth VE_coth │ │ VFx_coth VDx_coth VEx_coth │ └────────────────────────────────────────────────────────────────────────────┘ Function Hyperbolic cotangent function Syntax #include <VFmath.h> int VF_coth( fVector Y, fVector X, ui size ); int VFx_coth( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = coth ( Xi ) expanded versions: Yi = C * coth ( A*Xi+B ) Error handling SING errors lead to a default result of 0.0 (the mean of +HUGE_VAL and -HUGE_VAL); OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_sinh, VF_tanh, VF_exp, tanh ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cotrpi VD_cotrpi VE_cotrpi │ │ VF_cotrpi2 VD_cotrpi2 VE_cotrpi2 │ │ VF_cotrpi3 VD_cotrpi3 VE_cotrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Cotangent function of rational multiples of Pi Syntax #include <VFmath.h> int VF_cotrpi( fVector Y, iVector P, ui size, int q ); int VF_cotrpi2( fVector Y, iVector P, ui size, int q ); int VF_cotrpi3( fVector Y, iVector P, ui size, int q ); Description Yi = cot( (P[i] / q) * Pi ) The cotangent of fractional multiples of Pi is calculated. There are three versions: VF_cotrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_cotrpi2 should be used which is a highly optimized version using a look-up table. If q is a multiple of 3, VF_cotrpi3 should be used. VF_cotrpi2 and VF_cotrpi3 also work with q values they are not optimized for; in this case, however, memory space is wasted for the tables. Error handling SING errors occur if P[i] / q is a whole number. The default result is 0.0 (which is the mean of +HUGE_VAL and -HUGE_VAL); q must be non-zero; this is, however, not tested for. Return value 0, if no error occurred, otherwise non-zero. See also VF_cot, tan ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cprint VD_cprint VE_cprint │ │ VCF_cprint VCD_cprint VCE_cprint │ │ VI_cprint VSI_cprint VLI_cprint VQI_cprint │ │ VU_cprint VUS_cprint VUL_cprint VUI_cprint │ └────────────────────────────────────────────────────────────────────────────┘ Function print a vector to the screen Syntax #include <VFstd.h> VF_cprint( fVector X, ui size, unsigned nperline ); Description size elements of X are printed to the screen (or "console"), into the actual text window, nperline elements in each line. The display starts always with a new line. Please note that this may lead to an empty line at the beginning. Each line begins with the index of the first element printed into that line. The index is followed by a colon and by the requested nperline elements. Complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}. The display pauses every screenful. The user is prompted after each page to continue or to stop printing. The number of digits per element is determined by the available space, which depends in turn on the line width and on the parameter nperline. This family of functions is not available under Windows and should not be used within TurboVision programs. Error handling If nperline exceeds the maximum number of entries possible in the current text mode, an error message "Cannot use requested format (too many entries per line)!" is generated; in this case, the program chooses the maximum number nperline that is possible. Return value none See also cprintf, VF_fprint, VF_print, VF_write, VF_store ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoAbs VD_CtoAbs VE_CtoAbs │ └────────────────────────────────────────────────────────────────────────────┘ Function Absolute value (magnitude) of complex numbers Syntax #include <VCFstd.h> void VF_CtoAbs( fVector Abs, cfVector X, ui size ); Description Abs[i] = sqrt( Re²(Xi) + Im²(Xi) ) The absolute value, i.e. the magnitude of each element of the complex vector X is calculated. This function is almost identical to VCF_abs, but does not perform any error handling. Error handling none Return value none See also VCF_abs, VF_PolartoC, VF_CtoReIm, VF_CtoArg, VF_CtoNorm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoArg VD_CtoArg VE_CtoArg │ └────────────────────────────────────────────────────────────────────────────┘ Function Argument (angle) of complex numbers Syntax #include <VCFstd.h> void VF_CtoArg( fVector Arg, cfVector X, ui size ); Description Arg[i] = arctan( Im(Xi) / Re(Xi) ) The argument, i.e. the angle of each element of the complex vector X is calculated. For Cartesian coordinates {0, 0}, the angle is arbitrary and is set to zero. When necessary, depending on the signs of Re(Xi) and Im(Xi), Pi is added or subtracted from the arctan to obtain the correct quadrant. Error handling none Return value none See also VF_PolartoC, VF_CtoPolar, VF_atan2, VF_CtoAbs, VF_CtoReIm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoIm VD_CtoIm VE_CtoIm │ └────────────────────────────────────────────────────────────────────────────┘ Function Extract the imaginary part from a complex vector. Syntax #include <VCFstd.h> void VF_CtoIm( fVector Im, cfVector X, ui size ); Description The imaginary part of the complex vector X is extracted and stored in Im. Error handling none Return value none See also VF_CtoReIm, VF_ReImtoC, VF_ImtoC, VF_PolartoC, VF_extract ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoNorm VD_CtoNorm VE_CtoNorm │ └────────────────────────────────────────────────────────────────────────────┘ Function Norm (square of the absolute value) of complex numbers Syntax #include <VCFstd.h> void VF_CtoNorm( fVector Norm, cfVector X, ui size ); Description Norm[i] = Re²(Xi) + Im²(Xi) This definition of the Norm of a complex number is the same as in C++, but it is not consistent with the usual definition in mathematics, where the term "norm" is used as a synomym for "absolute value" or "magnitude". As defined here, the Norm is the square of the absolute value. The absolute value itself is available by the functions VF_CtoAbs (without error handling) and VCF_abs (with error handling). Error handling none Return value none See also VF_PolartoC, VF_CtoReIm, VF_CtoArg, VF_CtoAbs ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoPolar VD_CtoPolar VE_CtoPolar │ └────────────────────────────────────────────────────────────────────────────┘ Function Transformation of complex numbers from Cartesian into polar coordinates. Syntax #include <VCFstd.h> void VF_CtoPolar( fVector Mag, fVector Arg, cfVector X, ui size ); Description The polar coordinates Mag (magnitude, absolute value) and Arg (argument, angle) of each element of the Cartesian complex vector X are calculated. For the Cartesian coordinates {0, 0}, the polar coordinates are also set to {0, 0}. Error handling none Return value none See also VF_PolartoC, VF_CtoReIm, VF_CtoAbs, VF_CtoArg, VF_CtoNorm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoRe VD_CtoRe VE_CtoRe │ └────────────────────────────────────────────────────────────────────────────┘ Function Extracts the real part from a complex vector. Syntax #include <VCFstd.h> void VF_CtoRe( fVector Re, cfVector X, ui size ); Description The real part of the complex vector X is extracted and stored in Re. Error handling none Return value none See also VF_CtoReIm, VF_ReImtoC, VF_RetoC, VF_PolartoC, VF_extract ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_CtoReIm VD_CtoReIm VE_CtoReIm │ └────────────────────────────────────────────────────────────────────────────┘ Function Extracts the real and imaginary parts from a complex vector. Syntax #include <VCFstd.h> void VF_CtoReIm( fVector Re, fVector Im, cfVector X, ui size ); Description The real and imaginary parts of the complex vector X are extracted and stored in Re and Im, resp. Error handling none Return value none See also VF_CtoRe, VF_ReImtoC, VF_RetoC, VF_PolartoC, VF_extract ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_cubic VD_cubic VE_cubic │ │ VCF_cubic VCD_cubic VCE_cubic │ │ VFx_cubic VDx_cubic VEx_cubic │ │ VCFx_cubic VCDx_cubic VCEx_cubic │ └────────────────────────────────────────────────────────────────────────────┘ Function Cubic (third power) Syntax #include <VFmath.h> int VF_cubic( fVector Y, fVector X, ui size ); int VFx_cubic( fVector Y, fVector X, ui size, float A, float B ); Description normal versions: Yi = (Xi)**3 expanded versions: Yi = (A*Xi+B)**3 Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_square, VF_quartic, VF_sqrt, VF_pow, VF_ipow, VF_poly ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_dataPlot VCD_dataPlot VCE_dataPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Plot of a complex vector into an existing Cartesian complex plane. Syntax #include <Vgraph.h> void VCF_dataPlot( cfVector X, ui size, unsigned form, COLORREF color ); Description The vector X is plotted into a Cartesian complex plane that has to be already drawn by a prior call to either VCF_autoPlot, or VCF_2AutoPlot or V_drawAxes. For a description of the parameters form and color, see VF_xyAutoPlot. Error handling none Return value none See also VCF_autoPlot, VCF_2AutoPlot, VF_xyAutoPlot, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_deconvolve VD_deconvolve VE_deconvolve │ └────────────────────────────────────────────────────────────────────────────┘ Function Deconvolution Syntax #include <VFstd.h> void VF_deconvolve( fVector Y, fVector Flt, fVector X, fVector Rsp, ui size ); Description X is assumed to be the result of a convolution of some "true" profile with the response function Rsp; a deconvolution is attempted and stored in Y. A filter Flt is also calculated; if more than one vector is to be deconvolved with the same Rsp, use VF_deconvolve only once and use the filter Flt thus obtained to deconvolve other vectors by calling VF_filter. The response has to be stored in Rsp in wrap-around order: the elements for zero and positive times (or whatever the independent variable is) are stored as Rsp[0] to Rsp[size/2] and the elements for negative times as Rsp[size/2+1] to Rsp[size-1]. You may wish to use VF_rotate or VF_reflect to obtain the correct order when constructing the response vector. X, Y, Rsp, and Flt must all be of the same size, which has to be an integer power of 2. X may be overwritten by Y, Rsp may be overwritten by Flt, but X and Flt as well as Y and Rsp have to be distinct from each other. Mathematically, Flt is the inverse of the Fourier transform of Rsp. If the Fourier transform of Rsp contains elements equal to zero, all information is lost for the respective frequency and no reconstruction is possible. The best one can do in this case is to accept this loss and to deconvolve only up to those frequencies where still something is left to be reconstructed. You are therefore advised not to use this function blindly but rather to inspect the Fourier transform of Rsp and decide what to do on the basis of your specific application. If you wish to use this function nevertheless, you may rely on the automatic editing of the filter, built into VF_deconvolve. Thereby, Flt is set to zero (instead of infinity) at those frequences where all information has been lost. You may set the threshold for this implicit editing by VF_setRspEdit. In order to retrieve the threshold actually set, use VF_getRspEdit. This deconvolution is based on the implicit assumption that X is periodic; if this is not the case, see the description of VF_convolve about how to avoid end effects. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Error handling If size is not a power of 2, VF_FFT (on which VF_deconvolve is based) complains "Size must be an integer power of 2" and the program is aborted. If, by VF_setRspEdit, you specified Trunc.Re = Trunc.Im = 0, SING errors may occur that are handled by setting Flt to ±HUGE_VAL at the respective frequency. During multiplication with the transform of X, this may lead to unhandled floating- point overflow errors (in case your guess of Rsp was wrong and there is some information left at the frequencies where you thought it was not). Return value none See also VF_filter, VF_convolve, VF_FFT, VF_xcorr, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_delete VD_delete VE_delete │ │ VCF_delete VCD_delete VCE_delete │ │ VI_delete VSI_delete VLI_delete VQI_delete │ │ VU_delete VUS_delete VUL_delete VUI_delete │ └────────────────────────────────────────────────────────────────────────────┘ Function Delete one element from a vector Syntax #include <VFstd.h> void VF_delete( fVector X, ui size, ui pos ); Description This is one of the few functions where the input vector itself is changed, instead of being mapped onto an output vector. The element numbered pos is deleted from the vector, and all the following elements are shifted one position lower; the last element is left undefined. Error handling none Return value none See also VF_rotate, VF_insert ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_derivC VD_derivC VE_derivC │ └────────────────────────────────────────────────────────────────────────────┘ Function Derivative of an array with respect to an independent variable sampled at constant intervals Syntax #include <VFstd.h> void VF_derivC( fVector Y, fVector X, ui size, float DeltaT ); Description Y(t) = dX(t) / dt. The vector X is assumed to be a function of a variable t; the t values themselves are equally spaced. Therefore, only the spacing, DeltaT, must be passed to the function. By parabolic interpolation, the derivative of X with respect to t is calculated. This function does the inverse of the integration by VF_runintegralC. Error handling none Return value none See also VF_derivV, VF_runintegralC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_derivV VD_derivV VE_derivV │ └────────────────────────────────────────────────────────────────────────────┘ Function Derivative of one array with respect to another Syntax #include <VFstd.h> void VF_derivV( fVector Z, fVector X, fVector Y, ui size ); Description Z(X) = dY(X) / dX. The derivative of Y with respect to X is calculated by parabolic interpolation and stored in Z. If the elements of X are equally-spaced, it is better to use VF_derivC. The inverse procedure, i.e. integration, is performed by VF_runintegralV. Error handling none Return value none See also VF_derivC, VF_runintegralV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_distribution VD_distribution VE_distribution │ └────────────────────────────────────────────────────────────────────────────┘ Function Distribution function Syntax #include <VFstd.h> ui VF_distribution( uiVector Abund, fVector Limits, ui nbins, fVector X, ui sizex, int mode ); Description This function counts the number of elements of X falling into each of the intervals defined by Limits. The abundances thus determined are stored in Abund. nbins is the number of elements of Limits, i.e. the number of intervals. sizex is the size of X. Limits must be in ascending order. The spacing between the elements of Limits need not necessarily be constant. The parameter mode specifies how to interpret the values given in Limits. mode > 0: Limits contains the upper limits of the intervals mode < 0: Limits contains the lower limits of the intervals mode = 0: Limits contains the mid-points of the intervals. An element of X belongs to the element of Limits closest to it. In case of exactly equal dis- tances, the interval with the lower index is chosen. The interval defined by Limits[0] extends down to -HUGE_VAL, the interval defined by Limits[nbins-1] reaches up to +HUGE_VAL. The number of elements of X not falling into one of the intervals is returned. For mode > 0, these are the elements greater than the highest limit. For mode < 0, these are the elements smaller than the lowest limit. For mode = 0, the return value is always zero, because the intervals are open on both sides. So every element of X is accounted for in Abund. In order to get the normalized distribution function, use the sequence VF_distribution( Abund, Limits, nbins, X, sizex, 0 ); V_UItoD( Y, Abund, nbins ); VD_divC( Y, Y, nbins, VD_integralV(Limits,Y,nbins) ); After that, a call to VD_runintegralC( Y, Y, nbins, 1.0 ); yields the cumulated distribution function. Error handling none Return value number of elements of X not accounted for in Abund See also VF_searchV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_divC VD_divC VE_divC │ │ VCF_divC VCD_divC VCE_divC │ │ VCF_divReC VCD_divReC VCE_divReC │ │ VI_divC VSI_divC VLI_divC VQI_divC │ │ VU_divC VUS_divC VUL_divC VUI_divC │ └────────────────────────────────────────────────────────────────────────────┘ Function Divide by a constant Syntax #include <VFmath.h> void VF_divC( fVector Y, fVector X, ui size, float C ); void VCF_divC( cfVector Y, cfVector X, ui size, fComplex C ); void VCF_divReC( cfVector Y, cfVector X, ui size, float CRe ); Description Yi = Xi / C The integer versions perform an integer division, discarding the remainder; the remainder itself may be obtained by the functions of the VI_modC family. The complex floating-point versions exist in two variants, one for complex constants C, the other for real-valued constants CRe by which the complex vector is divided. Error handling none Return value none See also VF_divV, VF_addC, VF_subC, VF_mulC, VF_divrC, VF_modC, VF_visC, VF_redC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_divrC VD_divrC VE_divrC │ │ VCF_divrC VCD_divrC VCE_divrC │ │ VCF_divrReC VCD_divrReC VCE_divrReC │ │ VFx_divrC VDx_divrC VEx_divrC │ │ VCFx_divrC VCDx_divrC VCEx_divrC │ │ VI_divrC VSI_divrC VLI_divrC VQI_divrC │ │ VU_divrC VUS_divrC VUL_divrC VUI_divrC │ └────────────────────────────────────────────────────────────────────────────┘ Function Reverse division: divide a constant by a vector Syntax #include <VFmath.h> void VF_divrC( fVector Y, fVector X, ui size, float C ); void VFx_divrC( fVector Y, fVector X, ui size, float A, float B, float C ); void VCF_divrC( cfVector Y, cfVector X, ui size, fComplex C ); void VCFx_divrC( cfVector Y, cfVector X, ui size, fComplex A, fComplex B, fComplex C ); void VCF_divrReC( cfVector Y, cfVector X, ui size, float CRe ); Description normal versions: Yi = C / Xi expanded versions: Yi = C / (A*Xi+B) The complex floating-point versions exist in two variants, one for complex constants C, the other for real-valued constants CRe which are divided by the complex vector. Error handling none; for the floating-point versions, there are related functions that calculate 1.0 / Xi and 1.0 / (A*Xi+B): VF_inv and VFx_inv, respectively; both of these detect and handle SING errors. Return value none See also VF_divV, VF_inv, VF_addC, VF_subC, VF_mulC, VF_divC, VF_modC, VF_visC, VF_redC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_divrV VD_divrV VE_divrV │ │ VCF_divrV VCD_divrV VCE_divrV │ │ VCF_divrReV VCD_divrReV VCE_divrReV │ │ VFx_divrV VDx_divrV VEx_divrV │ │ VCFx_divrV VCDx_divrV VCEx_divrV │ │ VCFx_divrReV VCDx_divrReV VCEx_divrReV │ │ VI_divrV VSI_divrV VLI_divrV VQI_divrV │ │ VU_divrV VUS_divrV VUL_divrV VUI_divrV │ └────────────────────────────────────────────────────────────────────────────┘ Function Divide two vectors in reverse order Syntax #include <VFmath.h> void VF_divrV( fVector Z, fVector X, fVector Y, ui size ); void VFx_divrV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); void VCF_divrV( cfVector Z, cfVector X, cfVector Y, ui size ); void VCF_divrReV( cfVector Z, cfVector X, fVector Y, ui size ); void VCFx_divrV( cfVector Z, cfVector X, cfVector Y, ui size, fComplex A, fComplex B ); void VCFx_divrReV( cfVector Z, cfVector X, fVector Y, ui size, fComplex A, fComplex B ); Description normal versions: Zi = Yi / Xi expanded versions: Zi = Yi / (A*Xi+B) The complex floating-point versions exist in two variants: in the first variant (e.g., VCF_divrV, VCFx_divrV), X, Y, and Z are all complex; in the second variant, Y is real-valued (e.g., VCF_divrReV - "division in reverse order: divide a real vector by a complex one"). Error handling none Return value none See also VF_divrC, VF_addV, VF_mulV, VF_modV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_divV VD_divV VE_divV │ │ VCF_divV VCD_divV VCE_divV │ │ VCF_divReV VCD_divReV VCE_divReV │ │ VFs_divV VDs_divV VEs_divV │ │ VFx_divV VDx_divV VEx_divV │ │ VCFx_divV VCDx_divV VCEx_divV │ │ VCFx_divReV VCDx_divReV VCEx_divReV │ │ VI_divV VSI_divV VLI_divV VQI_divV │ │ VU_divV VUS_divV VUL_divV VUI_divV │ └────────────────────────────────────────────────────────────────────────────┘ Function Divide two vectors Syntax #include <VFmath.h> void VF_divV( fVector Z, fVector X, fVector Y, ui size ); void VFs_divV( fVector Z, fVector X, fVector Y, ui size, float C ); void VFx_divV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); void VCF_divV( cfVector Z, cfVector X, cfVector Y, ui size ); void VCF_divReV( cfVector Z, cfVector X, fVector Y, ui size ); void VCFx_divV( cfVector Z, cfVector X, cfVector Y, ui size, fComplex A, fComplex B ); void VCFx_divReV( cfVector Z, cfVector X, fVector Y, ui size, fComplex A, fComplex B ); Description normal versions: Zi = Xi / Yi scaled versions: Zi = C * (Xi / Yi) expanded versions: Zi = (A*Xi+B) / Yi The complex floating-point versions exist in two variants: in the first variant (e.g., VCF_divV, VCFx_divV), X, Y, and Z are all complex; in the second variant, Y is real-valued (e.g., VCF_divReV - "divide by a real vector"). Error handling none Return value none See also VF_divC, VF_addV, VF_mulV, VF_modV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ V_drawAxes │ └────────────────────────────────────────────────────────────────────────────┘ Function Draws a Cartesian coordinate system. Syntax #include <Vgraph.h> void V_drawAxes( long double Xmin, long double Xmax, long double Ymin, long double Ymax ); Description A Cartesian coordinate system is drawn with the axes scaled according to the values passed as Xmin, Xmax, Ymin, and Ymax. Ten subdivision lines are drawn on each axis. No adjustment of this scaling is performed; if automatic fine-tuning of the scaling is desired, call V_findAxes instead. Before using this function, either V_initGraph or V_initPlot has to be called. V_drawAxes is used internally by all functions of the AutoPlot family. Error handling none Return value none See also V_findAxes, V_initPlot, VF_xyAutoPlot, VF_xyDataPlot, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ V_DtoF V_DtoE │ └────────────────────────────────────────────────────────────────────────────┘ Function Data type conversions. See V_FtoD. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_equ0 VD_equ0 VE_equ0 │ │ VCF_equ0 VCD_equ0 VCE_equ0 │ │ VI_equ0 VSI_equ0 VLI_equ0 VQI_equ0 │ │ VU_equ0 VUS_equ0 VUL_equ0 VUI_equ0 │ └────────────────────────────────────────────────────────────────────────────┘ Function (Re-) initialize a vector with zero. Syntax #include <VFstd.h> void VF_equ0( fVector X, ui size ); Description Xi = 0 Error handling none Return value none See also VF_equ1, VF_equC, VF_equV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_equ1 VD_equ1 VE_equ1 │ │ VCF_equ1 VCD_equ1 VCE_equ1 │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialize a vector with 1.0. Syntax #include <VFstd.h> void VF_equ1( fVector X, ui size ); Description Xi = 1.0 In the complex versions, the imaginary parts are set to zero. Error handling none Return value none See also VF_equ0, VF_equC, VF_equV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_equC VD_equC VE_equC │ │ VCF_equC VCD_equC VCE_equC │ │ VI_equC VSI_equC VLI_equC VQI_equC │ │ VU_equC VUS_equC VUL_equC VUI_equC │ └────────────────────────────────────────────────────────────────────────────┘ Function Initializes a vector with a constant value. Syntax #include <VFstd.h> void VF_equC( fVector X, ui size, float C ); Description Xi = C Error handling none Return value none See also VF_equ0, VF_equ1, VF_equV, VF_comb ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_equV VD_equV VE_equV │ │ VCF_equV VCD_equV VCE_equV │ │ VFx_equV VDx_equV VEx_equV │ │ VCFx_equV VCDx_equV VCEx_equV │ │ VI_equV VSI_equV VLI_equV VQI_equV │ │ VU_equV VUS_equV VUL_equV VUI_equV │ └────────────────────────────────────────────────────────────────────────────┘ Function Copies one vector to another. Syntax #include <VFstd.h> void VF_equV( fVector Y, fVector X, ui size ); void VFx_equV( fVector Y, fVector X, ui size, float A, float B ); Description normal versions: Yi = Xi expanded versions: Yi = A * Xi + B Error handling none Return value none See also VF_equ0, VF_equ1, VF_equC, memcpy, memmove, movmem ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_Euclid VD_Euclid VE_Euclid │ └────────────────────────────────────────────────────────────────────────────┘ Function Calculates the Euclidean norm of a vector Syntax #include <VFstd.h> float VF_Euclid( fVector X, ui size ); Description norm = sqrt( sum( Xi² ) ) The Euclidean norm of a vector is defined as the square-root of the scalar product of the vector with itself. Error handling none (but beware of a possible overflow!) Return value The Euclidean norm is returned See also VF_ssq, VF_rms, VF_scalprod, VF_xprod ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_exp VD_exp VE_exp │ │ VCF_exp VCD_exp VCE_exp │ │ VFx_exp VDx_exp VEx_exp │ │ VCFx_exp VCDx_exp VCEx_exp │ └────────────────────────────────────────────────────────────────────────────┘ Function Exponential function Syntax #include <VFmath.h> int VF_exp( fVector Y, fVector X, ui size ); int VFx_exp( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = exp( Xi ) expanded versions: Yi = C * exp( A*Xi+B ) Euler's constant e is raised to the Xi'th power. Variants of the exponential function, like its complement (VF_expc), the hyperbolic functions (e.g. VF_sinh) or the Gaussian distribution (VF_Gauss) are also available; see chapter 4.6.6 about "Exponentials" before using VF_exp for sums or other combinations of exponentials - maybe the desired function already exists. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_log, VF_expc, VF_pow, VF_sinh, VF_exp2, VF_Gauss, exp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_exp2 VD_exp2 VE_exp2 │ │ VFx_exp2 VDx_exp2 VEx_exp2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Exponential function to the basis 2 Syntax #include <VFmath.h> int VF_exp2( fVector Y, fVector X, ui size ); int VFx_exp2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = 2 ** Xi expanded versions: Yi = C * 2 ** ( A*Xi+B ) Two is raised to the Xi'th power. These function names are used as synonyms for VF_pow2 etc. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_exp, VF_exp10, VF_ipow2, VF_scale2, VF_log2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_exp10 VD_exp10 VE_exp10 │ │ VFx_exp10 VDx_exp10 VEx_exp10 │ └────────────────────────────────────────────────────────────────────────────┘ Function Exponential function to the basis 10 Syntax #include <VFmath.h> int VF_exp10( fVector Y, fVector X, ui size ); int VFx_exp10( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = 10 ** Xi expanded versions: Yi = C * 10 ** ( A*Xi+B ) Ten is raised to the Xi'th power. These function names are used as synonyms for VF_pow10 etc. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_exp, VF_exp2, VF_ipow10, VF_scale10, VF_log10 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_expArbBase VD_expArbBase VE_expArbBase │ │ VCF_expArbBase VCD_expArbBase VCE_expArbBase │ │ VFx_expArbBase VDx_expArbBase VEx_expArbBase │ │ VCFx_expArbBase VCDx_expArbBase VCEx_expArbBase │ └────────────────────────────────────────────────────────────────────────────┘ Function Exponential function of an arbitrary base Syntax #include <VFmath.h> int VF_expArbBase( fVector Y, fVector X, ui size, float Base ); int VFx_expArbBase( fVector Y, fVector X, ui size, float Base, float A, float B, float C ); Description normal versions: Yi = Base ** Xi expanded versions: Yi = C * Base ** ( A*Xi+B ) Base must be positive and non-zero in the real-number versions. In the complex versions, Base must be non-zero. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_exp, VF_pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_expc VD_expc VE_expc │ │ VFx_expc VDx_expc VEx_expc │ └────────────────────────────────────────────────────────────────────────────┘ Function Calculate the "complementary exponential function" of each element of a vector. Syntax #include <VFmath.h> int VF_expc( fVector Y, fVector X, ui size ); int VFx_expc( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = 1 - exp( Xi ) expanded versions: Yi = C * (1 - exp [A*Xi + B ]) The difference between 1.0 and the exponential function of Xi is calculated. Note that the expc function is directly available from the 80x87 coprocessor in high accuracy; in fact, it is the exponential function itself that is internally calculated via the expc function. The expc function is often encountered in the natural sciences for the description of decay and growth processes. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_log, VF_exp, VF_pow, VF_sinh, VF_exp2, VF_Gauss, exp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_expmx2 VD_expmx2 VE_expmx2 │ │ VFx_expmx2 VDx_expmx2 VEx_expmx2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Exponential function of the negative square of the argument Syntax #include <VFmath.h> int VF_expmx2( fVector Y, fVector X, ui size ); int VFx_expmx2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = exp( -Xi² ) expanded versions: Yi = C * exp( -(A*Xi+B)² ) This function yields a bell-shaped curve similar to the Gaussian function. Error handling This function should be error-proof. Return value always 0 See also VF_log, VF_exp, VF_Gauss, VF_sech2, VF_Lorentz, exp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_FFT VD_FFT VE_FFT │ │ VCF_FFT VCD_FFT VCE_FFT │ └────────────────────────────────────────────────────────────────────────────┘ Function Fast Fourier transform Syntax #include <VFstd.h> void VF_FFT( fVector Y, fVector X, ui size, int dir ); Description The Fourier transform of X is calculated and stored in Y. The forward transform is obtained by setting dir = 1, the inverse (or backward) transform by setting dir = -1. A Fast Fourier Transform algorithm is used that requires size to be a power of 2. Complex version: Both X and the output Y are complex vectors. Real version: For the forward transform, X is a real vector. The output Y is also defined as fVector, although it consists of complex numbers. These are packed in a special way such as to fit into the same amount of memory as the original real vector X. The order of storage in Y is indicated in the following table (N=size, U is the uncompressed Fourier Transform of X): ┌─────────┬───────────┬─────────┬─────────┬────────┬────────────┬────────────┐ │ Y[0] │ Y[1] │ Y[2] │ Y[3] │ .......│ Y[N-2] │ Y[N-1] │ ├─────────┼───────────┼─────────┼─────────┼────────┼────────────┼────────────┤ │ U[0].Re │ U[N/2].Re │ U[1].Re │ U[1].Im │ .......│ U[N/2-1].Re│ U[N/2-1].Im│ └─────────┴───────────┴─────────┴─────────┴────────┴────────────┴────────────┘ The reason for this packing is the following. If the size real data points of X represent a function of the time, X = g(t), then the forward transform yields a function U = G(f) in the frequency domain. In principle, U consists of size+1 complex data points: size/2 points for positive frequencies, another size/2 points for negative frequencies, and one point at frequency zero. For the Fourier Transform of a real vector, the symmetry relation G(-f) = │G(f)│* holds (the asterisc denoting the complex conjugate). This means that the points at negative frequencies need not be stored; all information is already contained in the positive frequency half. Moreover, the zeroth and the size2'th element of the transform are both purely real. Therefore, only these two real and size/2-1 complex data points have to be stored - which exactly fit into the same amount of memory as the original size real data points of X. This allows X to be overwritten by its transform, if desired. In cases where it is more convenient to obtain the unpacked complex vector, the following sequence should to be used: Y = VCF_vector0( size ); /* create Y as a zeroed complex Vector */ VF_RetoC( Y, X, size ); /* Y.Re = X, Y.Im remains zero */ VCF_FFT( Y, Y, size, 1 ) ; /* transform Y */ For the real version of the inverse transform, X has to be a complex vector packed in the way just described, and a real- valued vector Y is obtained. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Error handling If size is not a power of 2, an error message "Size must be an integer power of 2" is generated and the program aborted. Return value none See also VF_filter, VF_convolve, VF_autocorr, VF_xcorr, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_filter VD_filter VE_filter │ │ VCF_filter VCD_filter VCE_filter │ └────────────────────────────────────────────────────────────────────────────┘ Function Frequency filtering Syntax #include <VFstd.h> void VF_filter( fVector Y, fVector X, fVector Flt, ui size ); Description A frequency filter Flt is applied to the vector X. Internally, this is done by performing a Fourier transform on X, multiplying the transform with Flt and transforming the product back into the time domain. Complex versions: X, Y and the filter Flt are complex vectors. Real versions: X and Y are real. Flt has to be in the packed complex format that is obtained by Fourier transforming a real vector with VF_FFT (see that function for the description of the packed complex format) or by using VF_convolve. If X is non-periodic, both ends of the filtered function may be spoiled by wrap-around. See VF_convolve about how to avoid end-effects by embedding X in a larger vector or by removing a possible linear trend. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Error handling If size is not a power of 2, VF_FFT (on which VF_filter is based) complains "Size must be an integer power of 2" and the program is aborted. Return value none See also VF_FFT, VF_convolve, VF_autocorr, VF_xcorr, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ V_findAxes │ └────────────────────────────────────────────────────────────────────────────┘ Function Calculate an appropriate scaling and draw a Cartesian coordinate system. Syntax #include <Vgraph.h> void V_findAxes( long double Xmin, long double Xmax, long double Ymin, long double Ymax ); Description This function will rarely be called by the user, but is used internally in VF_xyAutoPlot and other plotting functions. According to the x- and y ranges given in the parameters Xmin, Xmax, Ymin and Ymax, a linear Cartesian coordinate system is drawn with ten subdivisions both for the abscissa and the ordinate. If necessary, the x and y ranges are enlarged so as to meet the following conditions: 1. Every subdivision line represents an exact (and not only a rounded) value. 2. If the range of one axis or both includes zero, zero falls exactly on a subdivision line. If the automatic scaling is not desired, use V_drawAxes instead. Before calling V_findAxes, the plotting routines have to be initialized by either V_initGraph or V_initPlot. Error handling none Return value none See also V_drawAxes, V_initPlot, VF_xyAutoPlot ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_floor VD_floor VE_floor │ │ VF_floortoI VD_floortoI VE_floortoI │ │ VF_floortoSI VD_floortoSI VE_floortoSI │ │ VF_floortoLI VD_floortoLI VE_floortoLI │ │ VF_floortoQI VD_floortoQI VE_floortoQI │ │ VF_floortoU VD_floortoU VE_floortoU │ │ VF_floortoUS VD_floortoUS VE_floortoUS │ │ VF_floortoUL VD_floortoUL VE_floortoUL │ │ VF_floortoUI VD_floortoUI VE_floortoUI │ └────────────────────────────────────────────────────────────────────────────┘ Function Rounding towards minus infinity Syntax #include <VFmath.h> int VF_floor( fVector Y, fVector X, ui size ); int VF_floortoI( iVector Y, fVector X, ui size ); int VF_floortoLI( liVector Y, fVector X, ui size ); int VF_floortoU( uVector Y, fVector X, ui size ); (similarly all others) Description Each element of X is rounded to the nearest whole number that is less than or equal to the input number and the result stored in Y. The functions VF_floortoI, VF_floortoLI, VF_floortoU, etc. convert the result to the various integer data types (in the cases mentioned, to the types int, long int, or unsigned, respectively). Error handling OVERFLOW errors are handled by setting the result to the extreme value possible. Negative numbers in the versions VF_floortoU, VF_floortoUS, VF_floortoUL, and VF_floortoUI lead to DOMAIN errors; they are handled by setting the result to 0. Return value 0, if no error occurred, otherwise non-zero. See also ceil, floor, VF_round, VF_ceil, VF_chop, VF_trunc ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_flush0 VD_flush0 VE_flush0 │ │ VCF_flush0 VCD_flush0 VCE_flush0 │ └────────────────────────────────────────────────────────────────────────────┘ Function Sets vector elements with an absolute value less than a certain threshold to 0. Syntax #include <VFmath.h> void VF_flush0( fVector Y, fVector X, ui size, float AbsMin ); void VCF_flush0( fVector Y, fVector X, ui size, fComplex AbsMin ); Description Yi = Xi, if │ Xi │ >= AbsMin, Yi = 0, otherwise The complex versions treat the real and imaginary parts separately, using the real and imaginary parts of AbsMin to determine where to cut. If only the imaginary part is to be edited, set the real part of AbsMin to zero, e.g.: VCF_flush0( Y, X, size, fcplx( 0, 1.e-6 )); Error handling none Return value none See also VF_limit, VF_maxC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_fmodC VD_fmodC VE_fmodC │ │ VF_fmodV VD_fmodV VE_fmodV │ │ VFx_fmodV VDx_fmodV VEx_fmodV │ └────────────────────────────────────────────────────────────────────────────┘ Function Floating-point modulo division Syntax #include <VFmath.h> void VF_fmodC( fVector Y, fVector X, ui size, float C ); void VF_fmodV( fVector Z, fVector X, fVector Y, ui size ); void VFx_fmodV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); Description These functions have been included in order to provide consistency with ANSI C function names. They are implemented as macros that call VF_modC, VF_modV, VFx_modV etc. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_fprint VD_fprint VE_fprint │ │ VCF_fprint VCD_fprint VCE_fprint │ │ VI_fprint VSI_fprint VLI_fprint VQI_fprint │ │ VU_fprint VUS_fprint VUL_fprint VUI_fprint │ └────────────────────────────────────────────────────────────────────────────┘ Function print a vector to a stream Syntax #include <VFstd.h> VF_fprint( FILE *stream, fVector X, ui size, unsigned nperline, unsigned linewidth ); Description size elements of X are written to stream, nperline in each line of linewidth characters. Printing starts always with a new line. This may lead to an empty line at the beginning. Especially the first line of a file is reserved for a possible headline. Each line begins with the index of the first element printed into that line. The index is followed by a colon and by the requested nperline elements. Complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}. In contrast to VF_write and VF_nwrite, it is not possible to override the automatic choice of the format used for printing. The number of digits per element is determined by the available space, which depends in turn on the parameters nperline and linewidth. Error handling if nperline exceeds the maximum number of entries possible for the linewidth chosen, an error message "Cannot use requested format (too many entries per line)!" is generated; in this case, the program chooses the maximum number nperline possible. Return value none See also fprintf, VF_cprint, VF_print, VF_write, VF_store ┌────────────────────────────────────────────────────────────────────────────┐ │ V_free │ └────────────────────────────────────────────────────────────────────────────┘ Function De-allocate a single vector Syntax #include <VecLib.h> void V_free( void *X ); Description The vector X is freed (i.e. de-allocated). V_free should be used only for the de-allocation of vectors which have previously be allocated by one of the functions of the VF_vector or VF_vector0 family. To free several vectors simultaneously, use V_nfree. Error handling Trying to free a vector that has already been freed, or that has never been allocated memory, leads to a warning message "Cannot free non-existent vector". Program execution is continued without freeing anything in this case. Return value none See also V_nfree, V_freeAll, VF_vector, VF_vector0 ┌────────────────────────────────────────────────────────────────────────────┐ │ V_freeAll │ └────────────────────────────────────────────────────────────────────────────┘ Function De-allocate all vectors Syntax #include <VecLib.h> void V_freeAll( void ); Description All vectors previously be allocated by one of the functions of the VF_vector or VF_vector0 families are freed. Error handling none Return value none See also V_free, V_nfree, VF_vector, VF_vector0 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_frexp VD_frexp VE_frexp │ └────────────────────────────────────────────────────────────────────────────┘ Function Split up the elements of a vector into their mantissa and exponent parts. Syntax #include <VFmath.h> int VF_frexp( fVector Mant, iVector Exp, fVector X, ui size ); Description The function is implemented as a macro calling VF_mantexp; the name VF_frexp is included only to maintain consistency with the ANSI C function name frexp. For details, see VF_mantexp and frexp. ┌────────────────────────────────────────────────────────────────────────────┐ │ V_FtoD V_FtoE V_CFtoCD V_CFtoCE │ │ V_DtoF V_DtoE V_CDtoCF V_CDtoCE │ │ V_EtoF V_EtoD V_CEtoCF V_CEtoCD │ └────────────────────────────────────────────────────────────────────────────┘ Function Data type interconversions. Syntax #include <VDstd.h> (always include the <V..std.h> file of the destination data-type!) void V_FtoD( dVector Y, fVector X, ui size ); (similarly all other functions of this family) Description Each element of X is converted from the data type specified for X to the data type specified for Y and stored in Y. Error handling floating-point versions: OVERFLOW errors may occur in the course of the "down-conversions" (e.g., V_EtoF); by default, the extreme value possible for the destination data type is stored in Y with the correct sign. The occurrence of errors may be excluded by calling VE_limit or VD_limit (whichever is appropriate) prior to performing the data type conversion. Return value none See also VF_limit, V_ItoF, V_roundtoI, V_roundtoLI ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_Gauss VD_Gauss VE_Gauss │ └────────────────────────────────────────────────────────────────────────────┘ Function Gaussian normal distribution function. Syntax #include <VFmath.h> int VF_Gauss( fVector Y, fVector X, ui size, float Wid, float Cent, float C ); Description Yi = C / (Wid * sqrt(2*Pi)) * exp( -0.5*((Xi-Cent) / Wid)² ) Wid = width of the distribution Cent = center of the distribution C is a scaling factor; for C = 1.0, the distribution is normalized. For Wid = 0, the normal distribution is in fact a delta distribution with Y = C * INF at X = Cent and Y = 0 at all other values of X. Since infinities are not supported, the existence of a point X = Cent will lead to a SING error in case Wid is zero. Error handling SING errors may occur only for a Wid of zero. They are handled with the default result set to ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_exp, VF_sech2, VF_Lorentz, exp ┌────────────────────────────────────────────────────────────────────────────┐ │ V_getCoordSystem │ └────────────────────────────────────────────────────────────────────────────┘ Function Store the scalings and position of the current coordinate system used for VectorLib plotting operations Syntax #include <Vgraph.h> void V_getCoordSystem( VCOORDSYSTEM *csys ); Description If one wants to "hop" between several coordinate systems, displayed in one and the same window, one has to store the specifications (position and scalings) of each coordinate system separately, using this function. The address of a struct VCOORDSYSTEM is needed as the argument. VCOORDSYSTEM is defined in <Vgraph.h>. Example VCOORDSYSTEM csys1; .... /* create the first plot: */ V_setPlotRegion( 0, 0, 339, 200 ); VF_xyAutoPlot( X1, Y1, size1, PS_SOLID, LightGreen ); V_getCoordSystem( &csys1 ); /* store for later */ /* create the second plot: */ V_setPlotRegion( 340, 0, 679, 200 ); VF_xyAutoPlot( X2, Y2, size2, PS_SOLID, LightRed ); /* go back to the first plot: */ VF_setCoordSystem( &csys1 ); /* add an additional DataPlot: */ VF_xyDataPlot( X1, Z1, size1, PS_SOLID, LightBlue ); Error handling none Return value none See also V_setCoordSystem, V_setPlotRegion, V_continuePlot ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_getRspEdit VD_getRspEdit VE_getRspEdit │ └────────────────────────────────────────────────────────────────────────────┘ Function Read the present threshold for the editing of the filter in VF_convolve and VF_deconvolve Syntax #include <VFstd.h> fComplex VF_getRspEdit( void ); Description The threshold for the treatment of round-off errors in the functions for convolution and deconvolution is returned. Error handling none Return value present threshold. real part: acts on the real parts of the filter elements imaginary part: acts on the imaginary parts of the filter elements See also VF_setRspEdit, VF_convolve, VF_deconvolve ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_Hanning VD_Hanning VE_Hanning │ └────────────────────────────────────────────────────────────────────────────┘ Function "Hanning" window for use in spectral analysis Syntax #include <VFstd.h> void VF_Hanning( fVector X, ui size ); Description Xi = 0.5 * (1 - cos( 2 Pi i / (size-1) )) Error handling none Return value none See also VF_Welch, VF_Parzen, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_hypC VD_hypC VE_hypC │ └────────────────────────────────────────────────────────────────────────────┘ Function Quotient of Xi over the sum of Xi and a constant. Syntax #include <VFmath.h> void VF_hypC( fVector Y, fVector X, ui size, float C ); Description Yi = hyp( Xi, C ) = Xi / (Xi + C) The function calculating Yi according to this formula is dubbed "hyp" for its formal similarity to the expression constructing a hyperbola. Error handling none Return value none See also VF_hypV, VF_redC, VF_addC, VF_subC, VF_divC, VF_visC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_hypV VD_hypV VE_hypV, │ │ VFx_hypV VDx_hypV VEx_hypV │ └────────────────────────────────────────────────────────────────────────────┘ Function Quotient of Xi over the sum of Xi and Yi Syntax #include <VFmath.h> void VF_hypV( fVector Z, fVector X, fVector Y, ui size ); void VFx_hypV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); Description normal versions: Zi = hyp( Xi, Yi ) = Xi / (Xi + Yi) expanded versions: Zi = hyp( A*Xi+B), Yi ) Error handling none Return value none See also VF_hypC, VF_redV, VF_addV, VF_subV, VF_divV, VF_visV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_hypotC VD_hypotC VE_hypotC │ └────────────────────────────────────────────────────────────────────────────┘ Function Pythagoras "hypotenuse" function. Syntax #include <VFmath.h> int VF_hypotC( fVector Y, fVector X, ui size, float C ); Description Yi = sqrt( Xi² + C² ) This is a variant of the famous Pythagorean theorem for the hypotenuse of a right triangle. Error handling OVERFLOW errors lead to a default result of HUGE_VAL. Unlike the treatment of the ANSI C function hypot by several com- pilers, only an overflowing final result is regarded as an error. Intermediate overflows (by the calculation of the square) are avoided by appropriate scaling. Return value 0, if no error occurred; otherwise non-zero. See also VF_hypotV, VF_redC, VF_visC, VCF_abs, hypot ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_hypotV VD_hypotV VE_hypotV │ │ VFx_hypotV VDx_hypotV VEx_hypotV │ │ └────────────────────────────────────────────────────────────────────────────┘ Function Pythagoras "hypotenuse" function. Syntax #include <VFmath.h> int VF_hypotV( fVector Z, fVector X, fVector Y, ui size ); int VFx_hypotV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); Description normal version: Yi = sqrt( Xi² + Yi² ) expanded version: Yi = sqrt( (A*Xi+B)² + Yi² ) These are variants of the Pythagoras formula for the hypotenuse of a right triangle. Error handling OVERFLOW errors lead to a default result of HUGE_VAL. (Intermediate overflows are avoided by appropriate scaling.) Return value 0, if no error occurred; otherwise non-zero. See also VF_redC, VF_visC, VCF_abs, hypot ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_imag VCD_imag VCE_imag │ └────────────────────────────────────────────────────────────────────────────┘ Function Extracts the imaginary part from a complex vector. Implemented as a macro that calls VF_CtoIm, VD_CtoIm, VE_CtoIm, resp. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ImtoC VD_ImtoC VE_ImtoC │ └────────────────────────────────────────────────────────────────────────────┘ Function Overwrites the imaginary part of a complex vector with a real- valued vector. Syntax #include <VCFstd.h> void VF_ImtoC( cfVector Y, fVector Im, ui size ); Description The imaginary part of the complex vector Y is overwritten with the elements of the real-valued vector Im. The real part of Y is not affected. Error handling none Return value none See also VF_CtoReIm, VF_ReImtoC, VF_RetoC, VF_CtoIm, VF_PolartoC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_indpick VD_indpick VE_indpick │ │ VCF_indpick VCD_indpick VCE_indpick │ │ VI_indpick VSI_indpick VLI_indpick VQI_indpick │ │ VU_indpick VUS_indpick VUL_indpick VUI_indpick │ └────────────────────────────────────────────────────────────────────────────┘ Function Fill a vector with elements "picked" from another one according to their indices. Syntax #include <VFstd.h> void VF_indpick( fVector Y, uiVector Ind, ui size, fVector X ); Description Y[i] = X[ Ind[i] ], i=0,..size-1 The vector Y is filled with size elements taken from X according to their indices specified in Ind. The parameter size refers to Y and Ind. The size of X is unimportant, as long as the elements specified in Ind exist. Error handling none Return value none See also VF_indput, VF_subvector, VF_sortind ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_indput VD_indput VE_indput │ │ VCF_indput VCD_indput VCE_indput │ │ VI_indput VSI_indput VLI_indput VQI_indput │ │ VU_indput VUS_indput VUL_indput VUI_indput │ └────────────────────────────────────────────────────────────────────────────┘ Function Distribute the elements of one vector to the places within another vector specified by their indices. Syntax #include <VFstd.h> void VF_indput( fVector Y, fVector X, uiVector Ind, ui sizex ); Description Y[ Ind[i] ] = X[i], i=0,..sizex-1 The sizex elements of X are put into the places of Y accor- ding to the indices specified in Ind. The parameter sizex refers to X and Ind. The size of Y is unimportant, as long as the elements specified in Ind exist. Error handling none Return value none See also VF_indpick, VF_subvector, VF_sortind ┌────────────────────────────────────────────────────────────────────────────┐ │ V_initGraph │ └────────────────────────────────────────────────────────────────────────────┘ Function Initializes Borland's graphics system and the plotting functions of the VectorLib library (DOS only). Syntax #include <Vgraph.h> void V_initGraph( char *pathtodriver ); Description In DOS programs, this function is used to initialize Borland's graphics system by calling Borland's function initgraph and to initialize the VectorLib plotting functions (by internally calling V_initPlot). The search-path for graphics driver files has to be passed as a pointer to the string pathtodriver (see initgraph for details). The function uses initgraph to automatically detect the graphics driver present. This automatic detection ensures that programs may run on different PC systems without changes in the source code. If, however, it causes problems or for other reasons is not desired, do not use V_initGraph (but first initgraph and then V_initPlot). The global variable V_gmode is set to the graphics mode with the highest resolution possible for the detected graphics driver. If initgraph has already been called, do not use V_initGraph, but call only V_initPlot. Normally, V_initGraph will be called at the beginning of a program that uses graphics; to switch back into text mode within the program, use restorecrtmode. The next call to one of the AutoPlot functions switches again into graphics mode. You may also do that yourself by using setgraphmode( V_gmode ); (to do this, the declaration external int V_gmode; has to appear in the module containing this call). At the end of the program, free the memory allocated for graphics operations and go back to the standard mode with closegraph. Windows programs do not use the BGI routines. Consequently, BGI initialization is available only under DOS, but not under Windows. V_initPlot has to be used in order to prepare the VectorLib plotting operations under Windows. Error handling In case of failure, grapherrormsg is called, the appropriate error message displayed and the program aborted. Return value none See also V_initPlot, initgraph, closegraph, V_setPlotRegion, VF_xyAutoPlot, VF_yAutoPlot, VF_xyDataPlot, VCF_autoPlot ┌────────────────────────────────────────────────────────────────────────────┐ │ V_initPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialize the global variables used by the plotting functions Syntax #include <Vgraph.h> #ifdef _Windows void V_initPlot( HWND vwindow, HDC vdc ); #else void V_initPlot( int graphmode ); #endif Description DOS programs: If the graphics system has been initialized by a call to initgraph, V_initPlot is used to initialize the global constants necessary for the operation of the VectorLib plotting functions like VF_xyAutoPlot. If the graphics system is not yet initialized, use V_initGraph to initialize both the basic graphics system and the plotting functions; a call to V_initPlot is not necessary then. graphmode is the graphics mode set by initgraph. Windows programs: vwindow is the handle for a window and vdc the handle of a device context. As long as these handles remain valid, future plotting operations (like VF_xyAutoPlot) will be directed to the window specified by vwindow and use the fonts defined in the device context vdc. Be sure that vwindow and vdc are still valid when a plotting operation is performed; if in doubt, call V_initPlot again. If you use OWL, the handle of the actual window is always available as HWindow. DOS and Windows: V_initPlot reserves the rightmost about 2/3 of the screen for following plotting operations, leaving one line empty at the top of the screen and a few lines at the bottom. To override this, call V_setPlotRegion after V_initPlot. Error handling none Return value none See also V_initGraph, VF_xyAutoPlot, V_findAxes, V_drawAxes, V_setPlotRegion, V_initPrint ┌────────────────────────────────────────────────────────────────────────────┐ │ V_initPrint │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialize VectorLib plotting functions for use with a printer. Windows only! Syntax #include <Vgraph.h> void V_initPrint( HDC printdc ); Description This function exists only for Windows. It tells the VectorLib plotting functions to send their output to the printer context specified as printdc. By default, one whole page is reserved for the printout. To change this, call V_setPlotRegion after V_initPrint. To switch back to screen output, call V_initPlot. Error handling none Return value none See also V_initPlot, V_setPlotRegion, VF_xyAutoPlot ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_insert VD_insert VE_insert │ │ VCF_insert VCD_insert VCE_insert │ │ VI_insert VSI_insert VLI_insert VQI_insert │ │ VU_insert VUS_insert VUL_insert VUI_insert │ └────────────────────────────────────────────────────────────────────────────┘ Function Insert an element into a vector Syntax #include <VFstd.h> void VF_insert( fVector X, ui size, ui pos, float C ); Description This is one of the few functions where the input vector is changed itself (instead of being mapped onto an output vector). A new element is inserted at the position pos and has the value C. Elements before pos are unchanged, elements from pos on are shifted one position higher; the last element is lost. (If you wish to save the last element, choose size big enough to have a dummy element at the end of the vector; now it will be the dummy that gets lost.) Error handling none Return value none See also VF_delete, VF_rotate ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_integralC VD_integralC VE_integralC │ └────────────────────────────────────────────────────────────────────────────┘ Function Integral of an array plotted over an equally-spaced abscissa. Syntax #include <VFstd.h> float VF_integralC( fVector X, ui size, float DeltaT ); Description The vector X is assumed to be a function of a variable t; the t values themselves are equally spaced, so that only the spacing DeltaT is needed. The area under X, i.e. the integral of X over t from t[0] to t[size-1] is calculated. If not only the value of the integral is of interest, but a point-by-point integration has to be performed, VF_runintegralC should be used. Error handling none Return value The value of the integral is returned. See also VF_integralV, VF_runintegralC, VF_derivC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_integralV VD_integralV VE_integralV │ └────────────────────────────────────────────────────────────────────────────┘ Function Integral Syntax #include <VFstd.h> float VF_integralV( fVector X, fVector Y, ui size ); Description The vector Y is assumed to be a function of X; the integral of Y over X is calculated. If the elements of X are regularly spaced with a constant difference between them, the integral is obtained more efficiently by VF_integralC. If not only the value of the integral is of interest, but a point-by-point integration has to be performed, VF_runintegralV may be used. Error handling none Return value The value of the integral is returned. See also VF_integralC, VF_runintegralV, VF_derivV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_intfrac VD_intfrac VE_intfrac │ └────────────────────────────────────────────────────────────────────────────┘ Function Split up the elements of a vector into their integer and fractional parts. Syntax #include <VFmath.h> int VF_intfrac( fVector IntPart, fVector FracPart, fVector X, ui size ); Description The integer parts of the elements of X are stored in IntPart, the fractional parts in FracPart. Notice that IntPart is a floating-point vector, even though it contains integer numbers (which might be larger than could be stored in the integer data types). Error handling none Return value always 0 See also modf, VF_mantexp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_inv VD_inv VE_inv │ │ VFx_inv VDx_inv VEx_inv │ │ VCF_inv VCD_inv VCE_inv │ │ VCFx_inv VCDx_inv VCEx_inv │ └────────────────────────────────────────────────────────────────────────────┘ Function Inverse Syntax #include <VFmath.h> int VF_inv( fVector Y, fVector X, ui size ); int VFx_inv( fVector Y, fVector X, ui size, float A, float B ); Description normal versions: Yi = 1.0 / Xi expanded versions: Yi = 1.0 / (A*Xi+B) Error handling Division by zero is treated as a SING error with the default result set to HUGE_VAL. In the expanded versions, OVERFLOW errors may also occur; the default result is set to ±HUGE_VAL. Return value 0, if no error occurred; otherwise non-zero. See also VF_divrC, VF_divrV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ipow VD_ipow VE_ipow │ │ VCF_ipow VCD_ipow VCE_ipow │ │ VFx_ipow VDx_ipow VEx_ipow │ │ VCFx_ipow VCDx_ipow VCEx_ipow │ └────────────────────────────────────────────────────────────────────────────┘ Function Raise each element of a vector to a specified integer power. Syntax #include <VFmath.h> int VF_ipow( fVector Y, fVector X, ui size, int Expo ); int VFx_ipow( fVector Y, fVector X, ui size, int Expo, float A, float B, float C ); Description normal versions: Yi = Xi**Expo expanded versions: Yi = C * (A*Xi+B)**Expo If Expo is larger than a data-type dependent threshold (which will be a very rare occasion), VF_ipow does not calculate the result itself, but calls VF_pow, which is safer and faster in this case. Error handling SING errors occur, if zero is raised to a negative power; the default result is ±HUGE_VAL, as in the case of OVERFLOW errors. Return value 0, if no error occurred, otherwise non-zero See also VF_pow, VF_poly, VF_pow2, VF_exp, pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ipow10 VD_ipow10 VE_ipow10 │ └────────────────────────────────────────────────────────────────────────────┘ Function Integer powers of 10 Syntax #include <VFmath.h> int VF_ipow10( fVector Y, iVector X, ui size ); Description Yi = 10**Xi Notice: this function (and not VF_pow10 !) is the vectorized form of the function pow10 defined in Borland C/C++. Error handling OVERFLOW errors lead to a default result of HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_pow10, VF_scale10, VF_log10, VF_ipow, VF_exp, pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ipow2 VD_ipow2 VE_ipow2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Integer powers of 2 Syntax #include <VFmath.h> int VF_ipow2( fVector Y, iVector X, ui size ); Description Yi = 2**Xi Error handling OVERFLOW errors lead to a default result of HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_pow2, VF_scale2, VF_log2, VF_pow, VF_exp, pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_iselementC VD_iselementC VE_iselementC │ │ VCF_iselementC VCD_iselementC VCE_iselementC │ │ VI_iselementC VSI_iselementC VLI_iselementC VQI_iselementC │ │ VU_iselementC VUS_iselementC VUL_iselementC VUI_iselementC │ └────────────────────────────────────────────────────────────────────────────┘ Function Test if one or more elements of a table are equal to C. Syntax #include <VFstd.h> int VF_iselementC( fVector Tab, ui size, float C ); Description The vector Tab is searched for the value C. If one or more elements are equal to C, TRUE (+1) is returned, otherwise FALSE (0). No ordering of Tab is assumed and a linear search performed. A related function that finds the table element closest (but not necessarily equal) to C is VF_searchC. Error handling none Return value +1, if C is an element of X, otherwise 0. See also VF_searchC, VF_iselementV, lfind, lsearch ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_iselementV VD_iselementV VE_iselementV │ │ VCF_iselementV VCD_iselementV VCE_iselementV │ │ VI_iselementV VSI_iselementV VLI_iselementV VQI_iselementV │ │ VU_iselementV VUS_iselementV VUL_iselementV VUI_iselementV │ └────────────────────────────────────────────────────────────────────────────┘ Function Test for each element of a vector, if an identical element is present in a table. Syntax #include <VFstd.h> ui VF_iselementV( fVector Y, fVector X, ui sizex, fVector Tab, ui sizetab ); Description The table Tab is searched for each of the elements of X. For those elements of X which are found in Tab, the corresponding element of Y is set to +1 (in the complex versions: {1, 0} ). No ordering of X and Tab is assumed and a linear search for each Xi performed. A related function that finds the table element closest (but not necessarily equal) to each element of X is VF_searchV. Error handling none Return value The number of elements of X for which an element of Tab was found is returned. See also VF_searchV, VF_iselementC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ismonoton VD_ismonoton VE_ismonoton │ └────────────────────────────────────────────────────────────────────────────┘ Function Test if the elements of a vector are monotonously increasing or decreasing Syntax #include <VFstd.h> int VF_ismonoton( fVector X, ui size ); Description The vector X is analyzed. If the elements are in strict descending order, -1 is returned; if they are either constant or in strict ascending order, +1 is returned. Otherwise the return value is 0. If X contains passages that are increasing as well as passages that remain at a constant value, X is regarded as monotonous only if the increasing passage follows the constant passage, but not the other way round. Thus, the series 0, 0, 0, 1, 2, 3 will be accepted as monotonous (return value +1), whereas the series 1, 2, 3, 4, 4, 4 will not (return value 0). Also the initially constant, then falling series 0, 0, 0, -1, -2, -3 will not be regarded as monotonous. Error handling none Return value +1 in case of monotonous rise, or if all elements are identical, -1 in case of monotonously falling values, 0 if neither of these conditions is fulfilled. See also VF_sort ┌────────────────────────────────────────────────────────────────────────────┐ │ V_ItoF V_ItoD V_ItoE │ │ V_SItoF V_SItoD V_SItoE │ │ V_LItoF V_LItoD V_LItoE │ │ V_QItoF V_QItoD V_QItoE │ │ V_UtoF V_UtoD V_UtoE │ │ V_UStoF V_UStoD V_UStoE │ │ V_ULtoF V_ULtoD V_ULtoE │ │ V_UItoF V_UItoD V_UItoE │ └────────────────────────────────────────────────────────────────────────────┘ Function Convert integer numbers into floating-point data types. Syntax #include <VFstd.h> (always the include-file belonging to the destination type!) void V_ItoF( fVector Y, iVector X, ui size ); (all other functions of this family are similar) Description Each element of X is converted from the data type int, short int, long int, quad, unsigned, unsigned short, unsigned long, or ui, resp., into the data type float, double, or extended, resp., and stored in Y. For the inverse procedure, i.e. the conversion of floating-point numbers to integers, the functions of the VF_roundtoI, VF_floortoI, VF_ceiltoI, and VF_choptoI families have to be used. Error handling none Return value none See also VF_roundtoI, VF_floortoI, VF_ceiltoI, VF_choptoI, VF_trunctoI, V_ItoLI ┌────────────────────────────────────────────────────────────────────────────┐ │ V_ItoSI V_ItoLI V_ItoQI │ │ V_SItoI V_SItoLI V_SItoQI │ │ V_LItoSI V_LItoI V_LItoQI │ │ V_QItoSI V_QItoI V_QItoLI │ │ V_UtoUS V_UtoUL V_UtoUI │ │ V_UStoU V_UStoUL V_UStoUI │ │ V_ULtoU V_ULtoUS V_ULtoUI │ │ V_UItoU V_UItoUS V_UItoUL │ │ V_ItoU V_SItoUS V_LItoUL │ │ V_UtoI V_UStoSI V_ULtoLI │ └────────────────────────────────────────────────────────────────────────────┘ Function Interconversion of the integer data types Syntax #include <VLIstd.h> (or <VIstd.h>, <VUstd.h>,..., resp., depending on the destination data type!) void V_ItoLI( liVector Y, iVector X, ui size ); (all other functions of this family are similar) Description Each element of the vector X is converted into the desired data type and stored in Y. Error handling see chapter 5.2. Return value none See also V_ItoF ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ldexp VD_ldexp VE_ldexp │ └────────────────────────────────────────────────────────────────────────────┘ Function Scale by an integer power of 2. Syntax #include <VFmath.h> int VF_ldexp( fVector Y, fVector X, ui size, int expo ); Description These functions are implemented as alias names for VF_scale2 etc., in order to maintain consistency with the ANSI C function name ldexp. For details, see VF_scale2. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_limit VD_limit VE_limit │ │ VCF_limit VCD_limit VCE_limit │ └────────────────────────────────────────────────────────────────────────────┘ Function Limit the values of the elements of a vector to a specified range. Syntax #include <VFmath.h> void VF_limit( fVector Y, fVector X, ui size, float Min, float Max ); void VCF_limit( cfVector Y, cfVector X, ui size, fComplex Min, fComplex Max ); Description Real version: Yi = Xi , if Min <= Xi <= Max Yi = Max, if Xi > Max Yi = Min, if Xi < Min This function may be seen as a combination of VF_maxC and VF_minC. Complex version: Similar to the real version, but the real and imaginary parts are limited separately to the ranges specified in the respective parts of Min and Max. Error handling none Return value none See also VF_maxC, VF_minC, VF_min, VF_flush0 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_linregress VD_linregress VE_linregress │ └────────────────────────────────────────────────────────────────────────────┘ Function Linear regression Syntax #include <VFstd.h> void VF_linregress( fVector Param, fVector X, fVector Y, ui size ); Description The X-Y data are fitted to a straight line y = ax + b; the parameters a and b are determined in such a way that the quantity h² = sum( (Yi - y(x=Xi) )² ) is minimized. Uncertainties da and db are also determined. On output, Param is filled with the 5 elements {a, da, b, db, h²} in the order indicated. Error handling none Return value none See also VF_linregresswW, VF_corrcoeff, VF_chi2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_lincomb VD_lincomb VE_lincomb │ │ VCF_lincomb VCD_lincomb VCE_lincomb │ └────────────────────────────────────────────────────────────────────────────┘ Function linear combination of two vectors Syntax #include <VFstd.h> void VF_lincomb( fVector Z, fVector X, fVector Y, ui size, float CX, float CY ); Descirption Zi = CX * Xi + CY * Yi Error handling none Return value none See also VFx_addV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_linregresswW VD_linregresswW VE_linregresswW │ └────────────────────────────────────────────────────────────────────────────┘ Function Linear regression with weights Syntax #include <VFstd.h> void VF_linregresswW( fVector Param, fVector X, fVector Y, fVector InvVar, ui size ); Description The X-Y data are weighted with the inverse of their variances and fitted to a straight line y = ax + b; the parameters a and b are determined in such a way as to minimize the merit function chi² = sum( (1 / Var[i]) * (Yi - y(x=Xi) )² ) (see also VF_chi2). The inverse of the variance of each data point has to be passed to the function in the vector InvVar. Uncertainties da and db are also determined. On output, Param is filled with the 5 elements {a, da, b, db, chi²} in the order indicated. Error handling none Return value none See also VF_linregress, VF_corrcoeff, VF_chi2 ┌────────────────────────────────────────────────────────────────────────────┐ │ V_LItoF V_LItoD V_LItoE │ └────────────────────────────────────────────────────────────────────────────┘ Function Data type interconversions. See V_ItoF! ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ln VD_ln VE_ln │ │ VCF_ln VCD_ln VCE_ln │ │ VFx_ln VDx_ln VEx_ln │ │ VCFx_ln VCDx_ln VCEx_ln │ └────────────────────────────────────────────────────────────────────────────┘ Function Natural logarithm Syntax #include <VFmath.h> int VF_ln( fVector Y, fVector X, ui size ); int VFx_ln( fVector Y, fVector X, ui size, float A, float B, float C ); Description These function names are synonyms for the functions of the VF_log family. See VF_log for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_localmaxima VD_localmaxima VE_localmaxima │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the indices of local maxima Syntax #include <VFstd.h> ui VF_localmaxima( uiVector Ind, fVector X, ui size ); Description The indices of local maxima in X are stored in Ind and the number of local maxima is returned (this is the number of elements of Ind). A local maximum is defined as one element of X that is greater than both its neighbours to the right and to the left. That means that the zeroth and the last element of X (which have only one neighbour) cannot be local maxima. Also, if two adjacent elements are equal, none of them can be a local maximum. Error handling none Return value number of local maxima found See also VF_maxind, VF_max, VF_indpick, VF_localminima ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_localminima VD_localminima VE_localminima │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the indices of local minima Syntax #include <VFstd.h> ui VF_localminima( uiVector Ind, fVector X, ui size ); Description The indices of local minima in X are stored in Ind and the number of local minima is returned (this is the number of elements of Ind). A local minimum is defined as one element of X that is smaller than both its neighbours to the right and to the left. That means that the zeroth and the last element of X (which have only one neighbour) cannot be local minima. Also, if two adjacent elements are equal, none of them can be a local minimum. Error handling none Return value number of local minima found See also VF_minind, VF_min, VF_indpick, VF_localmaxima ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_log VD_log VE_log │ │ VCF_log VCD_log VCE_log │ │ VFx_log VDx_log VEx_log │ │ VCFx_log VCDx_log VCEx_log │ └────────────────────────────────────────────────────────────────────────────┘ Function Natural logarithm Syntax #include <VFmath.h> int VF_log( fVector Y, fVector X, ui size ); int VFx_log( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = ln( Xi ) expanded versions: Yi = C * ln( A*Xi+B ) The "logarithmus naturalis", i.e. the logarithm to the basis of Euler's constant e is calculated. Error handling Real versions: DOMAIN errors occur in the case of negative Xi (including -0.0), with NAN ("not-a-number") as the default result. SING errors occur for Xi= +0.0 and yield a result of -HUGE_VAL. In the complex version, numbers with an imaginary part of zero are always treated as real numbers; therefore, an argument {0, 0} is treated as a real 0, causing a SING error with the default result {-HUGE_VAL, 0}. Return value 0, if no error occurred, otherwise non-zero See also VF_exp, VF_log2, VF_log10, VF_pow, log ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_log10 VD_log10 VE_log10 │ │ VCF_log10 VCD_log10 VCE_log10 │ │ VFx_log10 VDx_log10 VEx_log10 │ │ VCFx_log10 VCDx_log10 VCEx_log10 │ └────────────────────────────────────────────────────────────────────────────┘ Function Decadic logarithm Syntax #include <VFmath.h> int VF_log10( fVector Y, fVector X, ui size ); int VFx_log10( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = lg( Xi ) expanded versions: Yi = C * lg( A*Xi+B ) The decadic logarithm (to the basis of 10) is calculated. Error handling Real versions: DOMAIN errors occur in the case of negative Xi (including -0.0), with NAN ("not-a-number") as the default result. SING errors occur for Xi= +0.0 and yield a result of -HUGE_VAL. In the complex version, numbers with an imaginary part of zero are always treated as real numbers; therefore, an argument {0, 0} is treated as a real 0, causing a SING error with the default result {-HUGE_VAL, 0}. Return value 0, if no error occurred, otherwise non-zero See also VF_pow10, VF_log, VF_log2, VF_pow, log10 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_log2 VD_log2 VE_log2 │ │ VCF_log2 VCD_log2 VCE_log2 │ │ VFx_log2 VDx_log2 VEx_log2 │ │ VCFx_log2 VCDx_log2 VCEx_log2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Binary logarithm Syntax #include <VFmath.h> int VF_log2( fVector Y, fVector X, ui size ); int VFx_log2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = lb( Xi ) expanded versions: Yi = C * lb( A*Xi+B ) The binary logarithm (to the basis 2) is calculated. Error handling Real versions: DOMAIN errors occur in the case of negative Xi (including -0.0), with NAN ("not-a-number") as the default result. SING errors occur for Xi= +0.0 and yield a result of -HUGE_VAL. In the complex version, numbers with an imaginary part of zero are always treated as real numbers; therefore, an argument {0, 0} is treated as a real 0, causing a SING error with the default result {-HUGE_VAL, 0}. Return value 0, if no error occurred, otherwise non-zero See also VF_pow2, VF_log, VF_log10, VF_pow, log2 (the latter function is not defined in ANSI C, but an addition contained in the VectorLib package, see chapter 9). ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_Lorentz VD_Lorentz VE_Lorentz │ └────────────────────────────────────────────────────────────────────────────┘ Function Lorentzian lineshape function Syntax #include <VFmath.h> int VF_Lorentz( fVector Y, fVector X, ui siz, float Wid, float Cent, float C ); Description Yi = C * Wid² / ( (Xi - Cent)² + Wid² ) Wid = width of the resonance line Cent = centre of the line C is a scaling factor; at the center of the line (Xi=Cent), the amplitude Yi equals C. This is even true for a width of zero. Error handling This function should be error-proof. Return value always 0 See also VF_Gauss, VF_sech2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_mantexp VD_mantexp VE_mantexp │ └────────────────────────────────────────────────────────────────────────────┘ Function Split up the elements of a vector into their mantissa and exponent parts Syntax #include <VFmath.h> int VF_mantexp( fVector MantPart, iVector ExpPart, fVector X, ui size ); Description The elements of X are split up into their mantissa, stored in MantPart, and exponent, stored as ints in ExpPart. Error handling none Return value always 0 See also VF_scale2, VF_intfrac, frexp, ldexp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_max VD_max VE_max │ │ VI_max VSI_max VLI_max VQI_max │ │ VU_max VUS_max VUL_max VUI_max │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the largest element of a vector. Syntax #include <VFstd.h> float VF_max( fVector X, ui size ); Description The vector X is searched for its largest element, whose value is returned. Error handling none Return value maximum value encountered. See also VF_min, VF_absmax, VF_runmax, VF_maxind ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_maxC VD_maxC VE_maxC │ │ VI_maxC VSI_maxC VLI_maxC VQI_maxC │ │ VU_maxC VUS_maxC VUL_maxC VUI_maxC │ └────────────────────────────────────────────────────────────────────────────┘ Function Compare each element of a vector to a constant and take the larger of the two. Syntax #include <VFmath.h> void VF_maxC( fVector Y, fVector X, ui size, float C ); Description Yi = Xi, if Xi > C Yi = C, if Xi <= C Error handling none Return value none See also VF_maxV, VF_minC, VF_max, VF_absmax, VF_limit, VF_flush0 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_maxind VD_maxind VE_maxind │ │ VI_maxind VSI_maxind VLI_maxind VQI_maxind │ │ VU_maxind VUS_maxind VUL_maxind VUI_maxind │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the largest element of a vector and its index. Syntax #include <VFstd.h> float VF_maxind( ui *Ind, fVector X, ui size ); Description The vector X is searched for its largest element; its value is returned. At the address passed as Ind, the index of this element is stored.In the case of several maxima of equal height, the first one is chosen (i.e., the smallest index is stored in Ind). Error handling none Return value maximum value encountered. See also VF_max, VF_minind, VF_absmax, VF_runmax ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_maxReIm VCD_maxReIm VCE_maxReIm │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the largest real and imaginary parts occurring in a vector. Syntax #include <VFmath.h> fComplex VCF_maxReIm( cfVector X, ui size ); Description The vector X is separately searched for its largest real and imaginary parts. Error handling none Return value struct of type fComplex (dComplex, eComplex, resp.), in which the maxima of the real and imaginary parts of X are packed together. See also VCF_minReIm, VCF_absmaxReIm, VCF_absmax, VCF_absmaxind ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_maxV VD_maxV VE_maxV │ │ VI_maxV VSI_maxV VLI_maxV VQI_maxV │ │ VU_maxV VUS_maxV VUL_maxV VUI_maxV │ └────────────────────────────────────────────────────────────────────────────┘ Function Compare each element of a vector to the corresponding element of another vector and take the larger of the two. Syntax #include <VFmath.h> void VF_maxV( fVector Z, fVector X, fVector Y, ui size ); Description Zi = Xi, if Xi > Yi Zi = Yi, if Xi <= Yi Error handling none Return value none See also VF_minV, VF_maxC, VF_max, VF_absmax ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_mean VD_mean VE_mean │ │ VCF_mean VCD_mean VCE_mean │ │ VI_mean VSI_mean VLI_mean VQI_mean │ │ VU_mean VUS_mean VUL_mean VUI_mean │ └────────────────────────────────────────────────────────────────────────────┘ Function Mean of a one-dimensional distribution Syntax #include <VFstd.h> float VF_mean( fVector X, ui size ); (similarly VD_, VE_, VCF_, VCD_, VCE_) double VI_mean( iVector X, ui size ); (similarly VSI_, VLI_, VU_, VUS_, VUL_, VUI_) extended VQI_mean( qiVector X, ui size ); Description mean = (1 / size) * sum( Xi ) Integer versions: the mean of a distribution consisting of whole numbers generally is a fractional, i.e. a floating- point number. Therefore, the return value of the 16-bit and 32-bit integer versions is a double. For the 64-bit integer version VQI_mean, the return value is an extended. Error handling none Return value Mean of the vector elements See also VF_meanwW, VF_median, VF_meanvar, VF_varianceC, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_meanabs VD_meanabs VE_meanabs │ └────────────────────────────────────────────────────────────────────────────┘ Function Mean of the absolute values of a one-dimensional distribution Syntax #include <VFstd.h> float VF_meanabs( fVector X, ui size ); Description meanabs = (1 / size) * sum(| Xi |) Error handling none Return value Mean of the absolute values of all vector elements See also VF_mean, VF_sumabs ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_meanvar VD_meanvar VE_meanvar │ └────────────────────────────────────────────────────────────────────────────┘ Function Mean and variance of a one-dimensional distribution Syntax #include <VFstd.h> float VF_meanvar( float *Var, fVector X, ui size ); Description mean = (1 / size) * sum( Xi ) var = (1 / (size-1)) * sum( (Xi - mean)² ) Note that the denominator in the definition of var is size-1, whereas, in the routine VF_varianceC, it is simply size.The reason for that difference is that here the mean is calculated first and then the variance is determined using this value, whereas in VF_varianceC, the parameter C is pre-set. The mean is returned and the variance stored at the address passed as Var. Error handling none Return value mean of the vector elements. See also VF_mean, VF_varianceC, VF_varianceV, VF_sum, VF_ssq, VF_ssqdevC, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_meanvarwW VD_meanvarwW VE_meanvarwW │ └────────────────────────────────────────────────────────────────────────────┘ Function Mean and variance with weights Syntax #include <VFmath.h> float VF_meanvarwW( float *Var, fVector X, fVector Wt, ui size ); Description mean = (1 / sum( Wti )) * sum( Xi * Wti ) var = (1 / sum( Wti )) * sum( Wti * (Xi - mean)² ) The weighted mean is returned and the variance stored at the address passed as Var. Error handling none Return value mean of the vector elements. See also VF_meanwW, VF_varianceCwW, VF_varianceVwW, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_meanwW VD_meanwW VE_meanwW │ │ VCF_meanwW VCD_meanwW VCE_meanwW │ └────────────────────────────────────────────────────────────────────────────┘ Function Mean with weights Syntax #include <VFstd.h> float VF_meanwW( fVector X, fVector Wt, ui size ); (similarly VD_, VE_) fComplex VCF_meanwW( cfVector X, fVector Wt, ui size ); (similarly VCD_, VCE_) Description meanwW = (1 / sum( Wti )) * sum( Xi * Wti ) Notice that, also in the complex version, the weights are always real and not complex. Error handling none Return value weighted mean of the vector elements. See also VF_mean, VF_sum, VF_ssq, VF_ssqdevC, VF_median, VF_mean_varwW, VF_linregresswW ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_median VD_median VE_median │ └────────────────────────────────────────────────────────────────────────────┘ Function Median of a one-dimensional distribution Syntax #include <VFmath.h> float VF_median( fVector X, ui size ); Description The median of a distribution is defined as the value for which values above and below are equally probable, i.e., for which the number of elements greater and less than the median is equal. If the table X is ordered, the median is simply the element with the index (size+1)/2 (if size is odd) or the mean of the two central elements (if size is even). If a table is not ordered, VF_median finds its median by repeatedly scanning through it without actually sorting it. Error handling none Return value The median is returned. See also VF_mean,VF_meanwW, VF_sum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_min VD_min VE_min │ │ VI_min VSI_min VLI_min VQI_min │ │ VU_min VUS_min VUL_min VUI_min │ └────────────────────────────────────────────────────────────────────────────┘ Function Finds the smallest (or the most negative) element of a vector. Syntax #include <VFstd.h> float VF_min( fVector X, ui size ); Description The vector X is searched for its smallest (or most negative) element. Error handling none Return value Minimum value encountered. See also VF_absmin, VF_runmin, VF_minind ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_minC VD_minC VE_minC │ │ VI_minC VSI_minC VLI_minC VQI_minC │ │ VU_minC VUS_minC VUL_minC VUI_minC │ └────────────────────────────────────────────────────────────────────────────┘ Function Compare each element of a vector to a constant and take the smaller of the two. Syntax #include <VFmath.h> void VF_minC( fVector Y, fVector X, ui size, float C ); Description Yi = Xi, if Xi <= C Yi = C, if Xi > C Error handling none Return value none See also VF_minV, VF_maxC, VF_min, VF_absmin, VF_limit, VF_flush0 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_minind VD_minind VE_minind │ │ VI_minind VSI_minind VLI_minind VQI_minind │ │ VU_minind VUS_minind VUL_minind VUI_minind │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the smallest (or the most negative) element of a vector and its index. Syntax #include <VFstd.h> float VF_minind( ui *Ind, fVector X, ui size ); Description The vector X is searched for its smallest (or most negative) element; its value is returned. At the address passed as Ind, the index of this element is stored. In the case of several mimima of equal depth, the first one is chosen (i.e., the smallest of their indices is stored in Ind). Error handling none Return value minimum value encountered. See also VF_min, VF_minind, VF_absmin, VF_runmin ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_minReIm VCD_minReIm VCE_minReIm │ └────────────────────────────────────────────────────────────────────────────┘ Function Find the smallest (or most negative) real and imaginary parts occurring in a vector. Syntax #include <VCFstd.h> fComplex VCF_minReIm( cfVector X, ui size ); Description The vector X is separately searched for its smallest real and imaginary parts. Error handling none Return value struct of type fComplex (dComplex, eComplex, resp.), in which the minima of the real and imaginary parts of X are packed together. See also VCF_maxReIm, VCF_absminReIm, VCF_absmin, VCF_absminind ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_minV VD_minV VE_minV │ │ VI_minV VSI_minV VLI_minV VQI_minV │ │ VU_minV VUS_minV VUL_minV VUI_minV │ └────────────────────────────────────────────────────────────────────────────┘ Function Compare each element of a vector to the corresponding element of another vector and take the smaller of the two. Syntax #include <VFmath.h> void VF_minV( fVector Z, fVector X, fVector Y, ui size ); Description Zi = Xi, if Xi <= Yi Zi = Yi, if Xi > Yi Error handling none Return value none See also VF_maxV, VF_minC, VF_min, VF_absmin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_modC VD_modC VE_modC │ │ VI_modC VSI_modC VLI_modC VQI_modC │ │ VU_modC VUS_modC VUL_modC VUI_modC │ └────────────────────────────────────────────────────────────────────────────┘ Function Modulus, i.e. the remainder of a division by a constant Syntax #include <VFmath.h> void VF_modC( fVector Y, fVector X, ui size, float C ); Description Yi = Xi mod C Floating-point versions: a constant C = 0.0 leads to all Yi being 0.0, independently of the Xi values (as in the ANSI C math function fmod ). Integer versions: a constant C = 0 leads to a ZERODIVIDE error (as in the intrinsic "%" operation of ANSI C). Error handling none Return value none (also the floating-point versions are treated as basic arithmetic rather than mathematical functions, despite their relation to the math function fmod). See also VF_modV, VF_addC, VF_mulC, VF_divC, VF_visC, VF_redC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_modf VD_modf VE_modf │ └────────────────────────────────────────────────────────────────────────────┘ Function Split up into integer and fractional parts. Syntax #include <VFmath.h> int VF_modf( fVector IntPart, fVector FracPart, fVector X, ui size ); Description These functions are implemented as alias names for VF_intfrac etc., in order to maintain consistency with the ANSI C function name modf. For details, see VF_intfrac. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_modV VD_modV VE_modV │ │ VFx_modV VDx_modV VEx_modV │ │ VI_modV VSI_modV VLI_modV VQI_modV │ │ VU_modV VUS_modV VUL_modV VUI_modV │ └────────────────────────────────────────────────────────────────────────────┘ Function Modulus, i.e. the remainder of a division of corresponding vector elements Syntax #include <VFmath.h> void VF_modV( fVector Z, fVector X, fVector Y, ui size ); void VFx_modV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); Description normal versions: Zi = Xi mod Yi expanded versions: Zi = (A * Xi + B) mod Yi Floating-point versions: an argument Xi = 0.0 leads to Zi being 0.0, independently of Yi (as in the ANSI C math function fmod). Integer versions: an argument Xi = 0 leads to a ZERODIVIDE error (as in the intrinsic "%" operation of ANSI C). Error handling none Return value none (also the floating-point versions are treated as basic arithmetic rather than mathematical functions, despite their relation to the math function fmod). See also VF_modC, VF_addV, VF_mulV, VF_divV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_mulC VD_mulC VE_mulC │ │ VCF_mulC VCD_mulC VCE_mulC │ │ VCF_mulReC VCD_mulReC VCE_mulReC │ │ VI_mulC VSI_mulC VLI_mulC VQI_mulC │ │ VU_mulC VUS_mulC VUL_mulC VUI_mulC │ └────────────────────────────────────────────────────────────────────────────┘ Function Multiply all vector elements by a constant Syntax #include <VFmath.h> void VF_mulC( fVector Y, fVector X, ui size, float C ); (similarly VD_, VE_, VI_, etc.) void VCF_mulC( cfVector Y, cfVector X, ui size, fComplex C ); void VCF_mulReC( cfVector Y, cfVector X, ui size, float CRe ); (similarly VCD_, VCE_) Description Yi = C * Xi The complex floating-point versions exist in two variants, one for complex constants C, the other for real-valued constants CRe by which the complex vector is multiplied. Error handling none Return value none See also VF_mulV, VF_addC, VF_divC, VF_divrC, VF_visC, VF_redC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_mulV VD_mulV VE_mulV │ │ VCF_mulV VCD_mulV VCE_mulV │ │ VCF_mulReV VCD_mulReV VCE_mulReV │ │ VFs_mulV VDs_mulV VEs_mulV │ │ VFx_mulV VDx_mulV VEx_mulV │ │ VCFx_mulV VCDx_mulV VCEx_mulV │ │ VCFx_mulReV VCDx_mulReV VCEx_mulReV │ │ VI_mulV VSI_mulV VLI_mulV VQI_mulV │ │ VU_mulV VUS_mulV VUL_mulV VUI_mulV │ └────────────────────────────────────────────────────────────────────────────┘ Function Multiply corresponding vector elements Syntax #include <VFmath.h> void VF_mulV( fVector Z, fVector X, fVector Y, ui size ); void VFs_mulV( fVector Z, fVector X, fVector Y, ui size, float C ); void VFx_mulV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); void VCF_mulV( cfVector Z, cfVector X, cfVector Y, ui size ); void VCF_mulReV( cfVector Z, cfVector X, fVector Y, ui size ); void VCFx_mulV( cfVector Z, cfVector X, cfVector Y, ui size, fComplex A, fComplex B ); void VCFx_mulReV( cfVector Z, cfVector X, fVector Y, ui size, fComplex A, fComplex B ); Description normal versions: Zi = Xi * Yi scaled versions: Zi = C * (Xi * Yi) expanded versions: Zi = (A * Xi + B) * Yi The complex floating-point versions exist in two variants: in the first variant (e.g. VCF_mulV, VCFx_mulV), X, Y, and Z are all complex; in the second variant, Y is real-valued (e.g. VCF_mulReV - "multiply by a real vector"). Error handling none Return value none See also VF_mulC, VF_addV, VF_subV, VF_divV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_neg VD_neg VE_neg │ │ VCF_neg VCD_neg VCE_neg │ │ VI_neg VSI_neg VLI_neg VQI_neg │ └────────────────────────────────────────────────────────────────────────────┘ Function Negation Syntax #include <VFmath.h> int VF_neg( fVector Y, fVector X, ui size ); Description Yi = - (Xi) VSI_, VI_, and VLI_ versions only: the negation of the most negative number possible (-32768 for short, -2147483648 for long) is again the same - negative! - number. This is due to the implicit modulo-2**n arithmetics, where the overflowing short +32768 is stored as -32768, and the overflowing long +2147483648 is stored as -2147483648. Error handling none Return value By analogy with VF_abs, the floating-point versions are treated as math functions. Therefore, they have a return value which, since no errors can occur, is always 0. The integer versions have no return value. See also VF_abs, VCF_conj ┌────────────────────────────────────────────────────────────────────────────┐ │ V_nfree │ └────────────────────────────────────────────────────────────────────────────┘ Function De-allocate memory occupied by one or more vectors. Syntax #include <VecLib.h> void V_nfree( unsigned numfree, ... ); Description The parameter numfree "tells" the function how many vectors it has to free. These vectors follow in the parameter list after numfree. De-allocation of vectors not allocated by one of the functions of the VF_vector or VF_vector0 family is dis- couraged, especially in Windows programs. Note for Turbo Pascal users: since a variable number of parameters is not supported in Turbo Pascal, this function is missing in VectorLib for Turbo Pascal. Example V_nfree( 3, X, Y, Z ); Error handling see V_free Return value none See also V_free, VF_vector, VF_vector0 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_noise VD_noise VE_noise │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialize a vector with "white" noise Syntax #include <VFstd.h> long VF_noise( fVector X, ui size, long seed, float Amp ); Description White noise is generated with the amplitude Amp, i.e., the output values are between -Amp/2 and +Amp/2 (both extrema included). seed may be chosen completely arbitrary; successive calls with the same seed yield identical results, for different values of seed, the obtained results are uncorrelated. Internally, these functions employ a 32-bit integer random number generator by H.W.Lewis, with additional steps (so- called "Bays-Durham shuffle") to break sequential correla- tions. This ensures very good randomness, far superior to simpler generators (like the rand function shipped with Borland C++). A long value is returned which may be used as new seed for subsequent calls. Error handling none Return value last 32-bit random number internally generated; may be used as new seed value for future calls. See also rand, random, VF_random ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_norm VCD_norm VCE_norm │ └────────────────────────────────────────────────────────────────────────────┘ Function Norm (square of the magnitude) of cartesian complex numbers. Implemented as macros calling VF_CtoNorm, VD_CtoNorm, and VE_CtoNorm, resp. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VI_not VSI_not VLI_not VQI_not │ │ VU_not VUS_not VUL_not VUI_not │ └────────────────────────────────────────────────────────────────────────────┘ Function Bit-wise complement Syntax #include <VImath.h> void VI_not( iVector Y, iVector X, ui size ); Description Yi = ~(Xi) Each single bit of the element Xi is inverted (i.e., it is 0 in Yi, if it was 1 in Xi, and vice versa). Error handling none Return value none See also VI_and, VI_or, VI_neg ┌────────────────────────────────────────────────────────────────────────────┐ │ V_noteError │ └────────────────────────────────────────────────────────────────────────────┘ Function Construct and print an error message Syntax #include <VecLib.h> void V_noteError( char *fname, unsigned why ); Description In case of an error, the math functions of VectorLib invoke the following steps: First call _matherr (or _matherrl), then inspect the return value of _matherr (or _matherrl) and call V_noteError in case this return value was 0. V_noteError then constructs the appropriate error message and passes it to V_printErrorMsg, which is the function in charge of actually printing the error message. By default, the message is printed to the screen. The function V_setErrorEventFile may be used to change this default action and to redirect the output into an event file (exclusively or in addition to the screen message). fname is the name of the "complaining" function and why specifies the reason for the complaint (as defined in <math.h> and described in connection with _matherr in the Borland C++ documentation). How to call V_noteError from a user-defined _matherr function is described in chapter 5.3. This function will not be included in versions of VectorLib for compilers that do already offer the possibility of printing error messages simultaneously to the screen and to an event file. Return value none See also V_setErrorEventFile, V_printErrorMsg, _matherr ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_nread VD_nread VE_nread │ │ VCF_nread VCD_nread VCE_nread │ │ VI_nread VSI_nread VLI_nread VQI_nread │ │ VU_nread VUS_nread VUL_nread VUI_nread │ └────────────────────────────────────────────────────────────────────────────┘ Function Read the columns of a table from a stream Syntax #include <VFstd.h> VF_nread( unsigned n, ui size, FILE *stream, ... ); Description n columns of a table are read into the vectors passed to VF_nread. The number of lines is specified as the number of elements of each vector, which is size. The entries of each line should be separated by spaces (' ') or tab characters ('\t'). Each line must be terminated by a line-feed character ('\n'). The length of the lines is limited according the following rules: - Either all lines have the same length. In this case, the length is determined automatically and might in principle be as large as 65535 characters. - Or the maximum length is given by the number n of vectors to be read and by the data type: VF_ 24*n VSI_, VUS_ 21*n VD_ 32*n VLI_, VUL_ 37*n VE_ 40*n VQI_ 32*n VCF_ 48*n VI_, VU_ as VSI_, VUS_ (in the VCD_ 64*n memory model FLAT as VCE_ 80*n VLI_, VUL_) It is possible to read fewer vectors than there are columns in a table. In this case, the trailing columns are neglected. If, however, you try to read more vectors than there are columns, the result is undefined and might lead to an error. Complex versions: Real und imaginary parts may (but need not) be enclosed in braces { }. However, you must be consequent: Either all or no element may be written with braces. Whole-number versions except VQI_nread: By default, the numbers to be read are interpreted as decimal numbers. You may use V_setRadix to define any radix between 2 and 36. Example VF_nread( 3, 100, DataFile, X, Y, Z ); Error handling Real, complex and quad versions: Overflowing numbers are silently truncated to ±HUGE_VAL. Whole-number versions except VQI_nread: As long as the numbers can be represented as long or unsigned long, overflowing bits are ignored in the 16-bit versions. Numbers beyond the long range yield -1 (signed types) or +HUGE_VAL (unsigned types). Return value none See also VF_nwrite, VF_read, VF_store, VF_recall, strtod, strtol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_nwrite VD_nwrite VE_nwrite │ │ VCF_nwrite VCD_nwrite VCE_nwrite │ │ VI_nwrite VSI_nwrite VLI_nwrite VQI_nwrite │ │ VU_nwrite VUS_nwrite VUL_nwrite VUI_nwrite │ └────────────────────────────────────────────────────────────────────────────┘ Function Write vectors as the columns of a table into a stream. Syntax #include <VFstd.h> VF_nwrite( FILE *stream, unsigned n, ui size, ... ); Description n vectors are written in ASCII format as the columns of a table into stream. The number of lines is given by the number of elements of each vector: size. The default format and separation may be changed using VF_setWriteFormat and VF_setNWriteSeparate, respectively. Example VF_nwrite( DataFile, 3, 100, X, Y, Z ); /* generates a table with 3 columns and 100 lines; the columns are given by X, Y and Z. */ Error handling none Return value none See also VF_write, VF_nread, VF_store, VF_recall, fprintf ┌────────────────────────────────────────────────────────────────────────────┐ │ VI_or VSI_or VLI_or VQI_or │ │ VU_or VUS_or VUL_or VUI_or │ └────────────────────────────────────────────────────────────────────────────┘ Function Bit-wise "OR" operation Syntax #include <VImath.h> void VI_or( iVector Y, iVector X, ui size, int C); void VUL_or( ulVector Y, ulVector X, ui size, unsigned long C ); Description Yi = (Xi) │ C The bit-wise "inclusive OR" operation is performed on each element Xi with the bit-mask given by C. A bit is 1 in Yi, if it was not simultaneously 0 in Xi and in C, i.e., if it was 1 at least in one of them. Error handling none Return value none See also VI_not, VI_and, VI_xor ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_Parzen VD_Parzen VE_Parzen │ └────────────────────────────────────────────────────────────────────────────┘ Function "Parzen" window for spectral analyses Syntax #include <VFmath.h> void VF_Parzen( fVector X, ui size ); Description Xi = 1 - │(i - 0.5*(size - 1)) / 0.5*(size + 1)│ Error handling none Return value none See also VF_Welch, VF_Hanning, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_polar VCD_polar VCE_polar │ └────────────────────────────────────────────────────────────────────────────┘ Function Construct Cartesian complex numbers from polar coordinates Implemented as a macro that calls VF_PolartoC, VD_PolartoC, VE_PolartoC, resp. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_PolartoC VD_PolartoC VE_PolartoC │ └────────────────────────────────────────────────────────────────────────────┘ Function Construct Cartesian complex numbers from polar coordinates Syntax #include <VFmath.h> void VF_PolartoC( cfVector X, fVector Mag, fVector Arg, ui size ); Description The polar coordinates Mag (magnitude, absolute value) and Arg (argument, angle) of each element are used to construct the Cartesian complex vector X. Error handling The total loss of precision for very large values of Arg is treated tacitly (without an error message); if it occurs, the result is set to {Magi, 0}. Return value none See also VF_CtoPolar, VF_ReImtoC, VF_CtoAbs, VF_CtoArg, VF_CtoNorm ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_poly VD_poly VE_poly │ │ VFx_poly VDx_poly VEx_poly │ └────────────────────────────────────────────────────────────────────────────┘ Function Polynomial Syntax #include <VFmath.h> int VF_poly( fVector Y, fVector X, ui size, fVector Coeff, unsigned deg ); int VFx_poly( fVector Y, fVector X, ui size, fVector Coeff, unsigned deg, float A, float B ); Description normal versions: Yi = c0 + c1 * Xi + c2 * Xi² + ... + cn * Xi**n expanded versions: xi = (A*Xi + B), Yi = c0 + c1 * xi + c2 * xi² + ... + cn * xi**n A polynomial of degree deg is generated for every element of X, using the coefficients contained in the vector Coeff. The coefficients in Coeff have to be ordered in such a way that the constant term is the zeroth element, the linear coefficient the first element etc., up to the deg'th element which is the coefficient for the highest power used in the polynomial. (Beware a frequent source of errors: for a polynomial of deg = 4, there are 5 (!) coefficients; do not forget the constant term). Error handling OVERFLOW errors lead to ±HUGE_VAL as the default result. In contrast to the ANSI C function poly (where deg is declared as int), the declaration of deg as unsigned precludes DOMAIN errors (which would occur for negative deg). Return value 0, if no error occurred, otherwise non-zero See also VF_ipow, VF_pow, poly ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_polyinterpol VD_polyinterpol VE_polyinterpol │ └────────────────────────────────────────────────────────────────────────────┘ Function Polynomial interpolation of X-Y-table values Syntax #include <VFstd.h> void VF_polyinterpol( fVector Y, fVector X, ui sizex, fVector XTab, fVector YTab, ui sizetab, unsigned deg ); Description For each of the sizex elements of X, the corresponding element of Y is interpolated from the XTab-YTab value pairs. XTab must be ordered (either ascending or descending). All values of XTab must be distinct; otherwise a division by zero may occur and lead to a program abort. For each element of X, the routine finds itself the appropriate place in the table. The parameter deg denotes the number of points that will be taken into account for the interpolation (this is not the degree of the interpolating polynomial!). Any value between 0 and 2 will be interpreted as meaning linear interpolation. A maximum of 10-point interpolation is possible. Error handling Trying to use too many elements for the interpolation (deg > 10) leads to an error message "Not possible with more than 10 elements" and to a program abort. If deg exceeds sizetab, an error message "Invalid parameter(s)" is displayed and the program aborted. No other errors are detected (you have to take care yourself that the XTab values are distinct and that the YTab values are not near the limit of overflowing). Return value none See also VF_ratinterpol, VF_splineinterpol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_pow VD_pow VE_pow │ │ VCF_pow VCD_pow VCE_pow │ │ VFx_pow VDx_pow VEx_pow │ │ VCFx_pow VCDx_pow VCEx_pow │ │ VCF_powReExpo VCD_powReExpo VCE_powReExpo │ │ VCFx_powReExpo VCDx_powReExpo VCEx_powReExpo │ └────────────────────────────────────────────────────────────────────────────┘ Function Raise each element of a vector to a specified power Syntax #include <VFmath.h> int VF_pow( fVector Y, fVector X, ui size, float Expo ); int VFx_pow( fVector Y, fVector X, ui size, float Expo, float A, float B, float C ); int VCF_pow( cfVector Y, cfVector X, ui size, fComplex Expo ); int VCFx_pow( cfVector Y, cfVector X, ui size, fComplex Expo, fComplex A, fComplex B, fComplex C ); int VCF_powReExpo( cfVector Y, cfVector X, ui size, float Expo ); int VCFx_powReExpo( cfVector Y, cfVector X, ui size, float Expo, fComplex A, fComplex B, fComplex C ); Description normal versions: Yi = Xi ** Expo expanded versions: Yi = C * ((A*Xi+B) ** Expo) If Expo is a moderately small integer number, the functions of this family pass the job to the appropriate routine of the VF_ipow family. More efficiently, the user could do just that himself. The complex version exists in two variants: one for complex exponents, the other for complex numbers raised to a real exponent. Error handling DOMAIN errors occur, if negative numbers are raised to fractional powers; the default result is NAN ("not-a-number"). SING errors occur, if zero is raised to a negative power; the default result is ±HUGE_VAL, which is true for OVERFLOW errors as well. Return value 0, if no error occurred, otherwise non-zero See also VF_ipow, VF_poly, VF_pow2, VF_exp, pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_pow10 VD_pow10 VE_pow10 │ │ VFx_pow10 VDx_pow10 VEx_pow10 │ └────────────────────────────────────────────────────────────────────────────┘ Function Real powers of 10 Syntax #include <VFmath.h> int VF_pow10( fVector Y, fVector X, ui size ); int VFx_pow10( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = 10.0 ** Xi expanded versions: Yi = C * 10.0 ** (A*Xi+B) This is an exponential function to the basis of 10.0. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_ipow10, VF_scale10, VF_log10, VF_pow, VF_exp, pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_pow2 VD_pow2 VE_pow2 │ │ VFx_pow2 VDx_pow2 VEx_pow2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Real powers of 2 Syntax #include <VFmath.h> int VF_pow2( fVector Y, fVector X, ui size ); int VFx_pow2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = 2.0 ** Xi expanded versions: Yi = C * 2.0 ** (A*Xi+B) This is an exponential function to the basis of 2.0. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_ipow2, VF_scale2, VF_log2, VF_pow, VF_exp, pow ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_print VD_print VE_print │ │ VCF_print VCD_print VCE_print │ │ VI_print VSI_print VLI_print VQI_print │ │ VU_print VUS_print VUL_print VUI_print │ └────────────────────────────────────────────────────────────────────────────┘ Function Print a vector as ASCII numbers to stdout, assuming a linewidth of 80 characters. Syntax #include <VFstd.h> VF_print( fVector X, ui size, unsigned nperline ); Description size elements of X are printed to stdout, nperline in each line. The available linewidth is assumed to be 80 characters. Each line begins with the index of the first element printed into that line. The index is followed by a colon and by the requested nperline elements. Complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}. In contrast to VF_cprint, no paging is performed. The number of digits per element is determined by the available space, which depends in turn on nperline. This family of functions is available under Windows only in connection with EasyWin, and should not be used within TurboVision programs. Error handling If nperline exceeds the maximum number of entries possible within 80 characters, an error message "Cannot use requested format (too many entries per line)" is generated; in this case, the program chooses the maximum number nperline possible. Return value none See also printf, VF_cprint, VF_fprint, VF_write, VF_store ┌────────────────────────────────────────────────────────────────────────────┐ │ V_printErrorMsg │ └────────────────────────────────────────────────────────────────────────────┘ Function Print an error message. Syntax #include <VecLib.h> void V_printErrorMsg( char *ErrMsg ); Description As described in connection with V_noteError, this function is in charge of printing error messages. By default, output is directed to the screen. The function V_setErrorEventFile may be used to redirect the output into an event file (exclusively or in addition to the screen message). V_printErrorMsg may be called from user-defined routines in which error conditions are detected. If the message is longer than one line, carriage returns ("\n" or "\r\n") have to be included at the desired place. Note, however, that this function will not be included in versions of VectorLib for compilers that do already offer the possibility of printing error messages simultaneously to the screen and to an event file. Return value none See also V_setErrorEventFile, V_noteError, _matherr ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_prod VD_prod VE_prod │ │ VCF_prod VCD_prod VCE_prod │ └────────────────────────────────────────────────────────────────────────────┘ Function Calculates the product of all the elements of a vector. Syntax #include <VFstd.h> float VF_prod( fVector X, ui size ); Description The product of all elements of a vector is calculated. Error handling none (but be careful: this function may easily overflow!) Return value the product of the vector elements See also VF_runprod, VF_sum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_quartic VD_quartic VE_quartic │ │ VCF_quartic VCD_quartic VCE_quartic │ │ VFx_quartic VDx_quartic VEx_quartic │ │ VCFx_quartic VCDx_quartic VCEx_quartic │ └────────────────────────────────────────────────────────────────────────────┘ Function Fourth power Syntax #include <VFmath.h> int VF_quartic( fVector Y, fVector X, ui size ); int VFx_quartic( fVector Y, fVector X, ui size, float A, float B ); Description normal versions: Yi = Xi ** 4 expanded versions: Yi = (A*Xi+B) ** 4 The fourth power of the elements of X is stored in Y. Error handling OVERFLOW errors lead to a default result of HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_square, VF_cubic, VF_sqrt, VF_pow, VF_ipow, VF_poly ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ramp VD_ramp VE_ramp │ │ VCF_ramp VCD_ramp VCE_ramp │ │ VI_ramp VSI_ramp VLI_ramp VQI_ramp │ │ VU_ramp VUS_ramp VUL_ramp VUI_ramp │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialize a vector with an ascending or descending "ramp". Syntax #include <VFstd.h> void VF_ramp( fVector X, ui size, float Start, float Rise ); (similarly VD_, VE_, VCF_, VCD_, VCE_, VI_, etc.) void VU_ramp( uVector X, ui size, unsigned Start, int Rise ); (similarly VUS_, VUL_) Description Xi = Start + i * Rise For the floating-point versions, remember the limited accuracy of floating-point numbers. For example, after calling VF_ramp( F1, 101, -1.0, 0.01 ); the element F1[100] will not be 0.0, as you might wish, but rather something like 2.2E-8. Ths is due to the fact that the number 0.01 (passed as a float to the function) is not exactly representable in the data type float. If that is a problem, consider building the ramp with moderately large integers and dividing by a scaling factor afterwards: VF_ramp( F1, 101, -100.0, 1.0 ); VF_divC( F1, F1, 101, 100.0 ); Note that Rise is defined as int instead of unsigned in the VU_ version and as long instead of unsigned long in the VUL_ version; this exception from the general rules - that all parameters in one function be of the same data type - allows to create descending ramps of unsigned numbers, which would not be possible otherwise. Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_Parzen, VF_Welch, VF_equ1, VF_random ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_random VD_random VE_random │ │ VI_random VSI_random VLI_random VQI_random │ │ VU_random VUS_random VUL_random VUI_random │ └────────────────────────────────────────────────────────────────────────────┘ Function High-quality random numbers Syntax #include <VFstd.h> long VF_random( fVector X, ui siz, long seed, float MinVal, float MaxVal ); Description The X vector is filled with a sequence of random numbers. Within the ranges defined by MinVal and MaxVal, and within the restrictions of floating-point representation, all numbers are equally probable (including the extreme values themselves), i.e., so-called "uniform deviates" are produced. The parameter seed may be any number. Successive calls to one and the same of these functions will yield identical sequences, if seed is chosen equal; if seed is chosen differently for successive calls, the results will be uncorrelated. Internally, these functions employ a 32-bit integer random number generator by H.W.Lewis, with additional steps (so- called "Bays-Durham shuffle") to break sequential correlations. This ensures very good randomness, far superior to simpler generators (like the rand function shipped with Borland C++). A long value is returned which may be used as new seed for subsequent calls. Error handling none Return value last 32-bit random number generated; this may be used as a new seed value for future calls. See also rand, srand, random, VF_noise ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ratinterpol VD_ratinterpol VE_ratinterpol │ └────────────────────────────────────────────────────────────────────────────┘ Function Diagonal-rational interpolation Syntax #include <VFmath.h> void VF_ratinterpol( fVector Y, fVector X, ui sizex, fVector XTab, fVector YTab, ui sizetab, unsigned deg ); Description For each of the sizex elements of X, the corresponding element of Y is interpolated from the XTab-YTab value pairs. XTab must be ordered (either ascending or descending). All values of XTab must be distinct; otherwise a division by zero may occur and lead to a program abort. The parameter deg denotes the number of points that will be taken into account for the interpolation; the diagonal rational interpolation scheme by Stoer and Bulirsch is used. The interpolating function is formed by the quotient of two polynomials, the polynomial in the denominator being of the same order (for even deg) or of an order higher by one (for odd deg) than the polynomial of the numerator. Diagonal rational interpolation is superior to polynomial interpolation, especially in the presence of poles. It is, however, much slower. deg must be between 3 and 20. Error handling A pole (infinity) in the interpolated function is recognized and leads to a SING error with the proposed result being ±HUGE_VAL. (Note: the x-value passed to _matherr is the first element of XTab). Trying to use too many elements for the interpolation (deg > 20) leads to an error message "Not possible with more than 20 elements" and to a program abort. If deg is not between 3 and 20, or exceeds sizetab, an error message "Invalid parameter(s)" is displayed and the program aborted. Return value none See also VF_polyinterpol, VF_splineinterpol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_read VD_read VE_read │ │ VCF_read VCD_read VCE_read │ │ VI_read VSI_read VLI_read VQI_read │ │ VU_read VUS_read VUL_read VUI_read │ └────────────────────────────────────────────────────────────────────────────┘ Function reads a vector in ASCII format from a stream Syntax #include <VFstd.h> VF_read( fVector X, ui size, FILE *stream ); Description size elements are read in ASCII format (up to 80 characters) from stream and stored in X. Normally, this function will be used to import vectors from a program which cannot store numbers in machine format. It can also be used to retrieve vectors previously stored by VF_write. For storing and retrieving intermediate results, however, the function pair VF_store / VF_recall is to be preferred over VF_write / VF_read (see VF_write). The entries to be read must be separated by whitespace (' ', '\n', or '\t'). Additionally, one (!) "non-whitespace" character is tolerated after each entry, if it follows directly after the last digit. After it, there must be one or more whitespace characters. Complex versions: Real und imaginary parts may (but need not) be enclosed in braces { }. However, you must be consequent: Either all or no element may be written with braces. Whole-number versions except VQI_nread: By default, the numbers to be read are interpreted as decimal numbers. You may use V_setRadix to define any radix between 2 and 36. Error handling Real, complex and quad versions: Overflowing numbers are silently truncated to ±HUGE_VAL. Whole-number versions except VQI_read: As long as the numbers can be represented as long or unsigned long, overflowing bits are ignored in the 16-bit versions. Numbers beyond the long range yield -1 (signed types) or +HUGE_VAL (unsigned types). Return value none See also VF_nread, VF_write, VF_store, VF_recall, strtod, strtol ┌────────────────────────────────────────────────────────────────────────────┐ │ VCF_real VCD_real VCE_real │ └────────────────────────────────────────────────────────────────────────────┘ Function Extracts the real part from a complex vector. Implemented as macros calling VF_CtoRe, VD_CtoRe, or VE_CtoRe, resp. See these functions for details. ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_recall VD_recall VE_recall │ │ VCF_recall VCD_recall VCE_recall │ │ VI_recall VSI_recall VLI_recall VQI_recall │ │ VU_recall VUS_recall VUL_recall VUI_recall │ └────────────────────────────────────────────────────────────────────────────┘ Function Read a vector in binary format from a stream Syntax #include <VFstd.h> VF_recall( fVector X, ui size, FILE *stream ); Description size elements of X are read from stream in binary format. Normally, these functions are used to retrieve data stored by the respective function of the VF_store family. Error handling none Return value none See also fwrite, fread, VF_store, VF_write, VF_print ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_redC VD_redC VE_redC │ └────────────────────────────────────────────────────────────────────────────┘ Function "Reduce" by a constant Syntax #include <VFmath.h> void VF_redC( fVector Y, fVector X, ui size, float C ); Description Yi = red( Xi, C ) = Xi * C / (Xi + C) Expressions of this type are frequently used in physics; for example, the "reduced mass" of a two-body system is the product of both masses divided by their sum. Error handling none Return value none See also VF_redV, VF_addC, VF_subC, VF_divC, VF_visC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_redV VD_redV VE_redV │ │ VFx_redV VDx_redV VEx_redV │ └────────────────────────────────────────────────────────────────────────────┘ Function "Reduce" by corresponding vector elements Syntax #include <VFmath.h> void VF_redV( fVector Z, fVector X, fVector Y, ui size ); void VFx_redV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); Description normal versions: Zi = red( Xi, Yi ) = Xi * Yi / (Xi + Yi) expanded versions: xi = (A * Xi + B), Zi = red( xi, Yi ) Error handling none Return value none See also VF_redC, VF_addV, VF_subV, VF_divV, VF_visV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_reflect VD_reflect VE_reflect │ │ VCF_reflect VCD_reflect VCE_reflect │ └────────────────────────────────────────────────────────────────────────────┘ Function Derive the second half of a vector from the first half by reflection at the midpoint. Syntax #include <VFstd.h> void VF_reflect( fVector X, ui size ); Description X[size-i-1] = X[i], i=0,...,(size-1)/2 The elements of the lower half of a vector are copied in reverse order into the upper half, i.e., the zeroth element is copied to the last, the element number 1 to the second last, and so on. The elements of the first half are not affected by this operation. This function will be used, e.g., to construct a response function for convolutions (see VF_convolve). In this case, note that the zeroth element is to appear only once in the response function and must not be included in the reflection by VF_reflect. Therefore, you have to calculate the response function for size/2+1 elements and to apply reflection from element 1 on. For an example, see VF_convolve. Error handling none Return value none See also VF_rotate, VF_rev, VF_convolve, VF_deconvolve, VF_filter ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ReImtoC VD_ReImtoC VE_ReImtoC │ └────────────────────────────────────────────────────────────────────────────┘ Function Construct a complex vector from real and imaginary parts Syntax #include <VCFstd.h> void VF_ReImtoC( cfVector Y, fVector Re, fVector Im, ui size ); Description The complex vector Y is constructed from two real vectors that become the real and imaginary parts of Y. Error handling none Return value none See also VF_CtoReIm, VF_RetoC, VF_PolartoC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_RetoC VD_RetoC VE_RetoC │ └────────────────────────────────────────────────────────────────────────────┘ Function Overwrite the real part of a complex vector with a real vector Syntax #include <VCFstd.h> void VF_RetoC( cfVector Y, fVector Re, ui size ); Description The real part of the complex vector Y is overwritten with the elements of the real-valued vector Re. The imaginary part of Y is not affected. Error handling none Return value none See also VF_CtoReIm, VF_ReImtoC, VF_ImtoC, VF_PolartoC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_rev VD_rev VE_rev │ │ VCF_rev VCD_rev VCE_rev │ │ VI_rev VSI_rev VLI_rev VQI_rev │ │ VU_rev VUS_rev VUL_rev VUI_rev │ └────────────────────────────────────────────────────────────────────────────┘ Function Reverse the ordering of the elements of a vector Syntax #include <VFstd.h> void VF_rev( fVector Y, fVector X, ui size ); Description Y[i] = X[size-i-1] Error handling none Return value none See also VF_reflect, VF_rotate ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_rms VD_rms VE_rms │ └────────────────────────────────────────────────────────────────────────────┘ Function Root of the mean square Syntax #include <VFstd.h> float VF_rms( fVector X, ui size ); Description rms = sqrt( (1/size) * sum( Xi² ) ) Error handling none Return value rms See also VF_ssq, VF_Euclid, VF_mean ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_rotate VD_rotate VE_rotate │ │ VCF_rotate VCD_rotate VCE_rotate │ │ VI_rotate VSI_rotate VLI_rotate VQI_rotate │ │ VU_rotate VUS_rotate VUL_rotate VUI_rotate │ └────────────────────────────────────────────────────────────────────────────┘ Function Rotate the ordering of the elements of a vector Syntax #include <VFstd.h> void VF_rotate( fVector Y, fVector X, ui size, int pos ); Description Y[i] = X[size-pos+i], i=0,..,pos-1 Y[i] = X[i-pos], i=pos,..,size-1 The output vector equals the rotated input vector. Clockwise rotation is achieved by a positive number pos. Error handling none Return value none See also VF_reflect, VF_rev ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_round VD_round VE_round │ │ VF_roundtoI VD_roundtoI VE_roundtoI │ │ VF_roundtoSI VD_roundtoSI VE_roundtoSI │ │ VF_roundtoLI VD_roundtoLI VE_roundtoLI │ │ VF_roundtoQI VD_roundtoQI VE_roundtoQI │ │ VF_roundtoU VD_roundtoU VE_roundtoU │ │ VF_roundtoUS VD_roundtoUS VE_roundtoUS │ │ VF_roundtoUL VD_roundtoUL VE_roundtoUL │ │ VF_roundtoUI VD_roundtoUI VE_roundtoUI │ └────────────────────────────────────────────────────────────────────────────┘ Function Rounding to the nearest whole number. Syntax #include <VFmath.h> int VF_round( fVector Y, fVector X, ui size ); int VF_roundtoI( iVector Y, fVector X, ui size ); int VF_roundtoLI( liVector Y, fVector X, ui size ); (similarly all other functions of this family) Description Each element of X is rounded to the nearest integer value. In case of a fractional part of exactly 0.5, the nearest even integer value is chosen and stored in Y. For example, 2.5 is rounded to 2, and 3.5 is rounded to 4. The functions VF_roundtoI, VF_roundtoLI, VF_roundtoU, etc. convert the result into the various integer data types. Error handling OVERFLOW errors are handled by setting the result to the extreme value possible. Negative numbers in the versions VF_roundtoU, VF_roundtoUS, VF_roundtoUL, and VF_roundtoUI lead to DOMAIN errors; they are handled by setting the result to 0. Return value Returns 0, if no error occurred, otherwise non-zero. See also round, floor, VF_round, VF_floor, VF_chop, VF_trunc ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_runintegralC VD_runintegralC VE_runintegralC │ └────────────────────────────────────────────────────────────────────────────┘ Function "running integral" of an array sampled at equally-spaced abscissa points. Syntax #include <VFstd.h> void VF_runintegralC( fVector Y, fVector X, ui size, float DeltaT ); Description The vector X is assumed to be a function of a variable t; the t values themselves are equally spaced. Therefore, only their spacing, DeltaT, must be known to the function. Each element of Y is the integral of all elements of X up to and including the one with the same index. Thus, the last element of Y contains the value of the integral over the whole of X (the area under X). If only this value is of interest, VF_integralC should be used. Error handling none Return value none See also VF_runintegralV, VF_integralC, VF_derivC, VF_runsum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_runintegralV VD_runintegralV VE_runintegralV │ └────────────────────────────────────────────────────────────────────────────┘ Function "running integral" Syntax #include <VFmath.h> void VF_runintegralV( fVector Z, fVector X, fVector Y, ui size ); Description Y is a function of the variable x which is represented by X. Each element of Z is the integral over all elements of Y up to and including the one with the same index. The first element of Z is always 0.0. The last element of Z is equal to the value of the integral, i.e. to the area under Y. If only this value of the integral is of interest, VF_integralV should be used. Error handling none Return value none See also VF_runintegralC, VF_integralV, VF_derivV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_runmax VD_runmax VE_runmax │ │ VI_runmax VSI_runmax VLI_runmax VQI_runmax │ │ VU_runmax VUS_runmax VUL_runmax VUI_runmax │ └────────────────────────────────────────────────────────────────────────────┘ Function "running" maximum. Syntax #include <VFstd.h> void VF_runmax( fVector Y, fVector X, ui size ); Description Each element of Y is the maximum of the corresponding and all preceding elements of X. Error handling none Return value none See also VF_max, VF_runmin, VF_runsum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_runmin VD_runmin VE_runmin │ │ VI_runmin VSI_runmin VLI_runmin VQI_runmin │ │ VU_runmin VUS_runmin VUL_runmin VUI_runmin │ └────────────────────────────────────────────────────────────────────────────┘ Function "running" minimum Syntax #include <VFstd.h> void VF_runmin( fVector Y, fVector X, ui size ); Description Each element of Y is the minimum of the corresponding and all preceding elements of X. Error handling none Return value none See also VF_min, VF_runmax, VF_runsum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_runprod VD_runprod VE_runprod │ │ VCF_runprod VCD_runprod VCE_runprod │ └────────────────────────────────────────────────────────────────────────────┘ Function "running" product Syntax #include <VFstd.h> void VF_runprod( fVector Y, fVector X, ui size ); Description Each element of Y is the product of the corresponding and all preceding elements of X. This function should be used with care: overflow is easily reached, and underflow may lead to all elements from a certain position on being zero. Error handling none Return value none See also VF_prod, VF_runsum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_runsum VD_runsum VE_runsum │ │ VCF_runsum VCD_runsum VCE_runsum │ │ VI_runsum VSI_runsum VLI_runsum VQI_runsum │ │ VU_runsum VUS_runsum VUL_runsum VUI_runsum │ └────────────────────────────────────────────────────────────────────────────┘ Function "running" sum Syntax #include <VFstd.h> void VF_runsum( fVector Y, fVector X, ui size ); Description Each element of Y is the sum of the corresponding and all preceding elements of X. Error handling none (but be careful: this function may easily overflow!) Return value none See also VF_sum, VF_runprod ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_scale10 VD_scale10 VE_scale10 │ └────────────────────────────────────────────────────────────────────────────┘ Function Scaling by an integer power of 10. Syntax #include <VFmath.h> int VF_scale10( fVector Y, fVector X, ui size, int expo ); Description Yi = Xi * (10 ** expo) Notice that higher powers of ten are not representable as exact numbers, which may lead to the introduction of round-off error by the scaling. If this is a problem, VF_scale2 should be used instead. Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_scale2, VF_mantexp, ldexp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_scale2 VD_scale2 VE_scale2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Scaling by an integer power of 2. Syntax #include <VFmath.h> int VF_scale2( fVector Y, fVector X, ui size, int expo ); Description Yi = Xi * (2 ** expo) Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_scale10, VF_mantexp, ldexp ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_scalprod VD_scalprod VE_scalprod │ └────────────────────────────────────────────────────────────────────────────┘ Function Scalar product of two vectors Syntax #include <VFstd.h> float VF_scalprod( fVector X, fVector Y, ui size ); Description scalprod = sum( Xi * Yi ) The scalar (or dot) product of two vectors is defined as the sum of the products of the corresponding elements. The scalar product of a vector with itself is the square of its magnitude and may be calculated using the function VF_ssq. Error handling none Return value scalar product See also VF_prod, VF_xprod, VF_sum, VF_ssq ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_searchC VD_searchC VE_searchC │ └────────────────────────────────────────────────────────────────────────────┘ Function Binary searches of an ordered table for the entry coming closest to a specified value Syntax #include <VFstd.h> ui VF_searchC( fVector X, ui size, float C, int mode ); Description In a binary search, the element of X is located that is closest to the value specified as C. X has to be an ordered table (either ascending or descending); if this condition is not fulfilled, the result will be wrong. If C is outside the range covered by X, the first or the last element of X is chosen, whichever is closer to C. If C is within the range of the table, three modes of the search are available: mode = +1: find the next element greater than or equal to C mode = 0: find the element closest to C; if two elements are within equal distance, choose the lower index mode = -1: find the next element less than or equal to C Error handling none Return value index of the element found. See also VF_searchV, VF_sort, VF_polyinterpol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_searchV VD_searchV VE_searchV │ └────────────────────────────────────────────────────────────────────────────┘ Function Binary search of an ordered table for the entries coming closest to the values specified as the elements of a vector Syntax #include <VFstd.h> void VF_searchV( uiVector Ind, fVector X, ui sizex, fVector Tab, ui sizetab, int mode ); Description For each element of X, the element of the ordered table Tab is located that is closest to it. If Xi is outside the range of the table, the first or the last element of the table is chosen, whichever is appropriate. Otherwise, three modes of the search are available: mode = +1: find the next element greater than or equal to Xi mode = 0: find the element closest to Xi; if two elements are within equal distance, choose the lower index mode = -1: find the next element less than or equal to Xi sizex is the number of elements of X and of Ind, whereas sizetab denotes the number of elements of the table Tab. Error handling none Return value none See also VF_searchC, VF_indpick, VF_sortind, VF_polyinterpol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sec VD_sec VE_sec │ │ VFx_sec VDx_sec VEx_sec │ └────────────────────────────────────────────────────────────────────────────┘ Function Secant function Syntax #include <VFmath.h> int VF_sec( fVector Y, fVector X, ui size ); int VFx_sec( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sec( Xi ) = 1 / cos( Xi ) expanded versions: Yi = C * sec( A*Xi+B ) The secant is defined as the inverse of the cosine (not to be mistaken for the arcus function arccos). For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as rational multiples of Pi, it is better to use VF_secrpi than VF_sec. Error handling SING or OVERFLOW errors lead to the default result ±HUGE_VAL. TLOSS precision errors lead to a result of 1.0 (as if the input were 0.0). Return value 0, if no error occurred, otherwise non-zero. See also VF_sec2, VF_secrpi, VF_cos, VF_sech, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sec2 VD_sec2 VE_sec2 │ │ VFx_sec2 VDx_sec2 VEx_sec2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the secant function Syntax #include <VFmath.h> int VF_sec2( fVector Y, fVector X, ui size ); int VFx_sec2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sec²( Xi ) expanded versions: Yi = C * sec²( A*Xi+B ) Calculating the squared trigonometric functions directly is faster and sometimes more accurate than first calculating the trigonometric function itself and squaring it afterwards. Error handling For SING and OVERFLOW errors, the default result is HUGE_VAL (multiplied by the sign of C in the expanded versions); TLOSS errors lead to a default result of 1.0 or C, resp. (as if the input were 0.0). Return value 0, if no error occurred, otherwise non-zero. See also VF_sec, VF_secrpi, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sech VD_sech VE_sech │ │ VFx_sech VDx_sech VEx_sech │ └────────────────────────────────────────────────────────────────────────────┘ Function Hyperbolic secant function Syntax #include <VFmath.h> int VF_sech( fVector Y, fVector X, ui size ); int VFx_sech( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sech( Xi ) = 2 / (exp( Xi ) + exp( -Xi )) expanded versions: Yi = C * sech( A*Xi+B ) Error handling These functions should be error-proof. Return value always 0 See also VF_sinh, VF_sech2, VF_exp, sinh ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sech2 VD_sech2 VE_sech2 │ │ VFx_sech2 VDx_sech2 VEx_sech2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the hyperbolic secant function Syntax #include <VFmath.h> int VF_sech2( fVector Y, fVector X, ui size ); int VFx_sech2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sech²( Xi ) expanded versions: Yi = C * sech²( A*Xi+B ) The sech² function is used in physics, e.g., to describe the shape of ultrashort light pulses. Compared to a Gaussian or Lorentzian pulse shape of the same autocorrelation width (see VF_autocorr), the sech² function has the smallest FWHM (full width to half maximum). Error handling These functions should be error-proof. Return value always 0 See also VF_sech, VF_sinh, VF_exp, VF_Gauss, VF_Lorentz ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_secrpi VD_secrpi VE_secrpi │ │ VF_secrpi2 VD_secrpi2 VE_secrpi2 │ │ VF_secrpi3 VD_secrpi3 VE_secrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Secant function of fractional multiples of Pi Syntax #include <VFmath.h> int VF_secrpi( fVector Y, iVector P, ui size, int q ); int VF_secrpi2( fVector Y, iVector P, ui size, int q ); int VF_secrpi3( fVector Y, iVector P, ui size, int q ); Description Yi = sec( (P[i] / q) * Pi ) The secant of fractional multiples of Pi is calculated. There are three versions: VF_secrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_secrpi2 should be used which is a highly optimized version utilizing a look-up table. If q is a multiple of 3, VF_secrpi3 should be used. VF_secrpi2 and VF_secrpi3 work also with q values they are not optimized for; in this case, however, memory space is wasted for the tables. Error handling SING errors occur if P[i] / q is an odd multiple of ½; the default result is 0.0 (which is the mean of +HUGE_VAL and -HUGE_VAL; similarly to VF_cosecrpi2, 0.0 is chosen irrespec- tive to the fact that it is not a valid result of the secant function!); q must be non-zero; this is, however, not tested for. Return value 0, if no error occurred, otherwise non-zero. See also VF_sec, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_selected_mean VD_selected_mean VE_selected_mean │ └────────────────────────────────────────────────────────────────────────────┘ Function Mean of the elements of a one-dimensional distribution, falling into a specified interval Syntax #include <VFstd.h> float VF_selected_mean( ui *nsel, fVector X, ui size float XMin, float XMax ); Description Those elements of X are selected, which fall into the interval XMin <= Xi <= XMax. Their mean is calculated, and the number of selected elements is stored at the address nsel. If this number is not needed, nsel may be passed to the function as NULL. Error handling none Return value Mean of the selected vector elements See also VF_mean ┌────────────────────────────────────────────────────────────────────────────┐ │ V_setCoordSystem │ └────────────────────────────────────────────────────────────────────────────┘ Function Restore the scalings and position of a coordinate system previously saved by V_getCoordSystem Syntax #include <Vgraph.h> void V_setCoordSystem( VCOORDSYSTEM *csys ); Description If one wants to "hop" between several coordinate systems, displayed in one and the same window, one has to store the specifications (position and scalings) of each coordinate system separately, using V_getCoordSystem, and to retrieve them as needed, using this function. The address of a struct VCOORDSYSTEM is passed as the argument. VCOORDSYSTEM is defined in <Vgraph.h>. For an example, see V_getCoordSystem. Error handling none Return value none See also V_getCoordSystem, V_setPlotRegion, V_continuePlot ┌────────────────────────────────────────────────────────────────────────────┐ │ V_setErrorEventFile │ └────────────────────────────────────────────────────────────────────────────┘ Function Prepare a file for printing error messages into it Syntax #include <VecLib.h> void V_setErrorEventFile( char *filename, unsigned ScreenAndFile ); Description This function determines where to print messages notifying math errors that occur within VectorLib routines. filename is the desired name of the event file (often called "log-file"). ScreenAndFile decides if you wish to have error messages printed simultaneously into the file and onto the screen (ScreenAndFile > 0) or exclusively into the file (ScreenAndFile = 0). If a user-defined _matherr function calls V_noteError, also errors occurring outside VectorLib routines will lead to a message printed into the event file (see Chapter 5.5). This function will not be included in versions of VectorLib for compilers which offer the possibility of printing error messages simultaneously to the screen and into an event file. The default, i.e., printing error messages to the screen, is restored by V_closeErrorEventFile. Error handling If the desired event file cannot be opened or created, the program is aborted with a message "Cannot open error event file". Return value none See also V_noteError, V_closeErrorEventFile, _matherr ┌────────────────────────────────────────────────────────────────────────────┐ │ V_setLineThickness │ └────────────────────────────────────────────────────────────────────────────┘ Function Modify the line thickness used in plotting functions Syntax #include <Vgraph.h> void V_setLineThickness( unsigned linethickness ); Description The line thickness used in the plotting functions VF_xyAutoPlot, VCF_autoPlot, etc., is set to linethickness. To reset the default value, call V_setLineThickness with linethickness = 1. DOS: There are only two possible values for linethickness: NORM_WIDTH=1 and THICK_WIDTH=3. Any value of linethickness below 3 is interpreted as NORM_WIDTH, any value above 3 is taken as THICK_WIDTH. Windows: Any value of linethickness between 1 and 500 is allowed, useful values ranging from 1 to about 10. A minimum thick- ness of one pixel is always secured, even if linethickness is set to 0. Note that broken or dotted lines are plotted accurately only with a linethicknes of 1. At higher values of linethickness, all lines will look like solid lines. Thicker lines are plotted considerably slower than thinner ones. Error handling DOS: "silent" correction of the input value. Windows: A value of linethickness greater than 500 leads to a warning message "Cannot use line thicker than 500 pixels." Program execution is continued with linethickness set to 500. Return value none See also VF_xyAutoPlot, V_setSymbolSize ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_setNWriteSeparate VD_setNWriteSeparate VE_setNWriteSeparate │ │ VCF_setNWriteSeparate VCD_setNWriteSeparate VCE_setNWriteSeparate │ │ VI_setNWriteSeparate VSI_setNWriteSeparate │ │ VLI_setNWriteSeparate VQI_setNWriteSeparate │ │ VU_setNWriteSeparate VUS_setNWriteSeparate │ │ VUL_setNWriteSeparate VUI_setNWriteSeparate │ └────────────────────────────────────────────────────────────────────────────┘ Function Definition of the string to be used by the V.._nwrite functions to separate table entries. Syntax #include <VFstd.h> void VF_setNWriteSeparate( char *SepString ); Description This function defines the character string to be inserted between the columns of a table written by VF_nwrite. VF_setNWriteSeparate does not influence the end of each line which is always a line-feed character ("\n"). SepString may contain up to twelve characters. The default setting is a tab character (#9). Error handling In the case of SepString longer than twelve characters, the program is aborted with the error message "Invalid Parameter(s)". The contents of SepString is not checked. Return value none See also VF_setWriteFormat, VF_setWriteSeparate, VF_nwrite, VF_nread ┌────────────────────────────────────────────────────────────────────────────┐ │ V_setPlotRegion │ └────────────────────────────────────────────────────────────────────────────┘ Function Defines a screen or printer-page region to be used by VectorLib plotting operations. Syntax #include <Vgraph.h> void V_setPlotRegion( int left, int top, int right, int bottom ); Description The rectangular region defined by the parameters, passed to V_setPlotRegion, will hold the coordinate system including all labels generated by future calls to VectorLib plotting functions such as VF_xyAutoPlot. The parameters left, top, right, and bottom are in pixels, counting from the upper left corner of the screen or of the printer page. V_setPlotRegion has to be called after (!) V_initPlot or V_initPrint. Error handling none Return value none See also V_initPlot, V_initPrint ┌────────────────────────────────────────────────────────────────────────────┐ │ V_setRadix │ └────────────────────────────────────────────────────────────────────────────┘ Function Define the radix for the whole-number read functions Syntax #include <VIstd.h> /* or <VSIstd.h>, <VLIstd.h>, <VUstd.h>, ... */ void V_setRadix( int radix ); Description By default, the V.._read functions for the whole-number data types interpret all numbers as decimal numbers. V_setRadix allows to change this default behaviour. The radix set by V_setRadix will be used in VI_read, VI_nread and their VSI_, VLI_, VUS_, VU_, VUL_, and VUL_ analogues. It does, however, not affect VQI_read or VQI_nread (where the radix is always 10). radix may take on values between 2 and 36 or 0. In the case of radix=0, the basis of each number is determined at run-time: All numbers beginning with the ciphers 1-9 are recognized as decimal numbers. All numbers beginning with "0x" are interpreted as hexadecimal and all numbers beginning with "0" without "x" are read as octal numbers. Error handling radix < 0, radix=1, or radix > 36 lead to a program abort with the error message "Invalid Parameter(s)". Return value none See also VI_read, VI_nread, strtol, strtoul ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_setRspEdit VD_setRspEdit VE_setRspEdit │ └────────────────────────────────────────────────────────────────────────────┘ Function Modify the treatment of round-off errors in VF_convolve and VF_deconvolve Syntax #include <VFstd.h> void VF_setRspEdit( fComplex Trunc ); Description In the functions VF_convolve and VF_deconvolve, a frequency filter is calculated by Fourier-transforming a given response function. The filter is then applied to a vector. Due to accumulated round-off, filter elements that should be zero may be not so, but contain small non-zero numbers. The maximum round-off error in the construction of Flt accumulates roughly to (size * big * prec), where big is the largest element of Flt and prec the relative floating-point precision. Any element smaller than that should be regarded as zero. In order to determine the exact threshold for the real and imaginary parts separately, the function uses the real and imaginary parts of Trunc, substituting them for prec in the above expression. Normally, you would choose Trunc.Re = Trunc.Im, although a stricter (i.e. larger) value for Trunc.Im is also reasonable. By default, Trunc.Re = 16*EPSILON and Trunc.Im = 32*EPSILON, where EPSILON is FLT_EPSILON, DBL_EPSILON, or LDBL_EPSILON (these constants are defined in <float.h>), depending on the data type. In order to switch the editing of the filter completely off, choose Trunc.Re = Trunc.Im = 0. During convolutions, the editing of the filter leads to slightly smoother results. During deconvolutions, the editing has also another meaning: for all "lost" frequencies (i.e., those for which the Fourier transform of the response function contains only numbers near zero), the filter is set to 0 instead of the inverse of these small numbers. Thereby, possible OVERFLOW and SING errors are avoided. To read the currently set threshold, call VF_getRspEdit. Error handling none Return value none See also VF_convolve, VF_deconvolve, VF_getRspEdit ┌────────────────────────────────────────────────────────────────────────────┐ │ V_setSymbolSize │ └────────────────────────────────────────────────────────────────────────────┘ Function Modify the size of the symbols used in plotting functions Syntax #include <Vgraph.h> void V_setSymbolSize( float symsiz ); Description The size of the symbols used in the plotting functions VF_xyAutoPlot, VCF_autoPlot, etc., is modified by scaling with symsiz. To reset the symbol size to the default value, call V_setSymbolSize with symsiz=1.0. Note that it is not possible to make the symbols completely vanish (e.g., by setting symsiz = 0.0), since a minimum radius of one pixel is always secured. Useful values of symsiz range from about 0.5 to 5.0. Values above 50.0 are prohibited. When magnifying the symbols, you should also consider modifying the thickness of the connecting lines, if you are using any. See V_setLineThickness. Notice: An automatic scaling is always performed in order to maintain a constant relation between the symbol size and the overall size of the coordinate grid (which is especially important for Windows applications). The factor symsiz of this function scales the symbol size with respect to the automatically-found value. The automatic scaling cannot be switched off. Error handling DOS: "silent" correction of the input value. Windows: A value of symsiz greater than 50.0 leads to a warning message "Cannot scale symbols by more than a factor of 50.0". Program execution is continued with symsiz set to 50.0. Return value none See also VF_xyAutoPlot, V_setLineThickness ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_setWriteFormat VD_setWriteFormat VE_setWriteFormat │ │ VCF_setWriteFormat VCD_setWriteFormat VCE_setWriteFormat │ │ VI_setWriteFormat VSI_setWriteFormat │ │ VLI_setWriteFormat VQI_setWriteFormat │ │ VU_setWriteFormat VUS_setWriteFormat │ │ VUL_setWriteFormat VUI_setWriteFormat │ └────────────────────────────────────────────────────────────────────────────┘ Function Definition of the format to be used by V.._write and V.._nwrite Syntax #include <VFstd.h> void VF_setWriteFormat( char *FormatString ); Description The functions of the VF_write and VF_nwrite families employ internally the ANSI C function fprintf in order to print numbers into a stream. According to the rules described in the documentation of Borland C++ for printf, the format may be specified as fits your needs. When defining a write format, one should always be aware of the restrictions imposed by the read functions (not all formats you can write will be read correcly, see VF_read). VF_setWriteFormat should not be used for the definition of whitespace before or after the numbers. This is the task of VF_setWriteSeparate. For details about the formats used for each of the various data types, please refer to the following table. The last column of this table gives the maximum length of the format string. │ Version │ Standard Format │ Alternative Example │max.length │ ├─────────┼────────────────────────┼─────────────────────────┼───────────┤ │ VF_ │ "% 11.8e" │ "% 8.4f" │ 16 │ │ VD_ │ "% 19.16le" │ "% 16.8lf" │ 16 │ │ VE_ │ "% 22.19Le" │ "% 22.19LG" │ 16 │ │ VCF_ │ "% 11.8e, % 11.8e" │ "{% 8.4f, % 8.4f}" │ 32 │ │ VCD_ │ "% 19.16le, % 19.16le" │ "{% 19.16lE % 19.16lE}" │ 32 │ │ VCE_ │ "% 22.19Le, % 22.19Le" │ "{% 22.19Lg % 22.19Lg}" │ 32 │ │ VI_ │ "% 5d" │ "0x% 4x" │ 12 │ │ VSI_ │ "% 5hd" │ "0x% 4hX" │ 12 │ │ VLI_ │ "% 10ld" │ "%08lXh" │ 12 │ │ VQI_ │ "% 20.0Lf" │ │ 16 │ │ VU_ │ "% 5u" │ "%04xh" │ 12 │ │ VUS_ │ "% 5hu" │ "0%04ho" │ 12 │ │ VUL_ │ "% 10lu" │ "0%08lO" │ 12 │ └─────────┴────────────────────────┴─────────────────────────┴───────────┘ The data type quad is converted into extended before being passed to fprintf (which, at present, does not support quads). This explains why the format string in the VQI_ version tells fprintf to expect a long double. In the memory model FLAT of the registered version of VectorLib, the VI_ variant gets the standard format "% 10d" and the VU_ variant gets the standard format "% 10u". Error handling Format strings longer than the maximum length specified in the above table lead to a program abort with the error message "Invalid Parameter(s)". The contents of the format string is not checked. So you have to be very careful to specify a format which is valid for the respective data type. Return value none See also VF_setWriteSeparate, VF_write, VF_nwrite, VF_read, VF_nread ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_setWriteSeparate VD_setWriteSeparate VE_setWriteSeparate │ │ VCF_setWriteSeparate VCD_setWriteSeparate VCE_setWriteSeparate │ │ VI_setWriteSeparate VSI_setWriteSeparate │ │ VLI_setWriteSeparate VQI_setWriteSeparate │ │ VU_setWriteSeparate VUS_setWriteSeparate │ │ VUL_setWriteSeparate VUI_setWriteSeparate │ └────────────────────────────────────────────────────────────────────────────┘ Function Definition of the separation string used by V.._write Syntax #include <VFstd.h> void VF_setWriteSeparate( char *SepString ); Description By default, VF_write puts a line feed character after each vector element written into a stream. This means that each element gets its own line. You may use VF_setWriteSeparate to define another separation string. This may be, for example, a tab character ("\t") or a series of spaces (e.g., " "). If you use VF_write with the output sent directly to the printer (stream = stdprn), you probably have to explicitly use a carriage return character in addition to the line feed. To do this, call VF_setWriteSeparate( "\n\r" ); VF_write will insert the separation string only in between the vector elements. At the end, after the last element, there is always a line feed ("\n") instead of the separation string. SepString may contain up to twelve characters. Error handling In the case of SepString longer than twelve characters, the program is aborted with the error message "Invalid Parameter(s)". The contents of SepString is not checked. Return value none See also VF_setWriteFormat, VF_setNWriteSeparate, VF_write, VF_read ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sgn VD_sgn VE_sgn │ └────────────────────────────────────────────────────────────────────────────┘ Function Signum function, compares each element of a vector with 0. Syntax #include <VFmath.h> void VF_sgn( fVector Y, fVector X, ui size ); Description Each element of X is compared with 0 and the result of the comparison stored in Y: Yi = +1.0, if Xi > 0 Yi = 0.0, if Xi = 0 Yi = -1.0, if Xi < 0. This function is implemented as a macro that calls VF_cmp0. Error handling none Return value none See also VF_cmp_..., VF_cmpC, VF_cmpV ┌────────────────────────────────────────────────────────────────────────────┐ │ VI_shl VSI_shl VLI_shl VQI_shl │ │ VU_shl VUS_shl VUL_shl VUI_shl │ └────────────────────────────────────────────────────────────────────────────┘ Function "Shift to the left", i.e. multiply by integer powers of 2. Syntax #include <VImath.h> void VI_shl( iVector Y, iVector X, ui size, unsigned C ); void VUL_shl( ulVector Y, ulVector X, ui size, unsigned C ); (similarly all other functions of this family) Description Yi = Xi << C All bits of Xi are shifted to the left by as many positions as indicated in the parameter C. This corresponds to a multiplication by 2**C, neglecting possible overflow (in all versions) and loss of the sign bit (for signed numbers, i.e. in the VI_, VSI_, VLI_, and VQI_ versions). Note that by shifting 16-bit numbers (VSI_, VUS_ versions) by more than 15 positions, any non-zero bit present in the original number is lost and the result is 0. Similarly, 32-bit numbers (VLI_, VUL_ versions) yield 0 upon shifting by more than 31 positions. C is always of the data type unsigned. Shifting by negative numbers C is, therefore, not possible. To perform a right-shift, the appropriate function of the VI_shr family has to be used. Error handling none Return value none See also VI_mul, VI_shr ┌────────────────────────────────────────────────────────────────────────────┐ │ VI_shr VSI_shr VLI_shr VQI_shr │ │ VU_shr VUS_shr VUL_shr VUI_shr │ └────────────────────────────────────────────────────────────────────────────┘ Function "Shift to the right", i.e., divide by integer powers of 2. Syntax #include <VImath.h> void VI_shr( iVector Y, iVector X, ui size, unsigned C ); void VUL_shr( ulVector Y, ulVector X, ui size, unsigned C ); (similarly all other functions of this family) Description Yi = Xi >> C All bits of Xi are shifted to the right by as many positions as indicated in the parameter C. This corresponds to an integer division by 2**C. The sign of Yi is always the same as of Xi. In contrast to explicit integer divisions, the result is always rounded toward minus infinity: -15 / 2 = -7, but -15 >> 1 = -8. Note that by shifting 16-bit numbers (VSI_, VUS_ versions) by more than 15 positions, any unsigned or positive number yields 0, whereas any negative number (in the VSI_ version) yields -1 in this case. The same is true for 32- bit numbers (VLI_, VUL_ versions) upon shifting by more than 31 positions. C is always of the data type unsigned. Shifting by negative numbers C is, therefore, not possible. To perform a left-shift, the appropriate function of the VI_shl family has to be used. Error handling none Return value none See also VI_div, VI_shl ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sin VD_sin VE_sin │ │ VCF_sin VCD_sin VCE_sin │ │ VFx_sin VDx_sin VEx_sin │ │ VCFx_sin VCDx_sin VCEx_sin │ └────────────────────────────────────────────────────────────────────────────┘ Function Sine function Syntax #include <VFmath.h> int VF_sin( fVector Y, fVector X, ui size ); int VFx_sin( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sin( Xi ) expanded versions: Yi = C * sin( A*Xi+B ) For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as fractional multiples of Pi, it is better to use VF_sinrpi than VF_sin. Error handling Precision errors lead to a default result of 0.0 and a non- zero return value, but are ignored otherwise; _matherr is not called. OVERFLOW errors can only occur in the complex versions and lead to a result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_sin2, VF_sinrpi, VF_cos, VF_sinh, VF_asin, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sin2 VD_sin2 VE_sin2 │ │ VFx_sin2 VDx_sin2 VEx_sin2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the sine function Syntax #include <VFmath.h> int VF_sin2( fVector Y, fVector X, ui size ); int VFx_sin2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sin²( Xi ) expanded versions: Yi = C * sin²( A*Xi+B ) Calculating the squared trigonometric functions directly is faster and sometimes more accurate than first calculating the trigonometric function itself and squaring it afterwards. Error handling Precision errors lead to a default result of 0.0 and a non- zero return value, but are otherwise ignored; _matherr is not called. OVERFLOW errors can only occur in the complex versions and lead to a result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_sin, VF_sinrpi, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sinc VD_sinc VE_sinc │ │ VFx_sinc VDx_sinc VEx_sinc │ └────────────────────────────────────────────────────────────────────────────┘ Function Sinc function Syntax #include <VFmath.h> int VF_sinc( fVector Y, fVector X, ui size ); int VFx_sinc( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sinc( Xi ) = sin( Xi ) / Xi expanded versions: Yi = C * sinc( A*Xi+B ) The sinc function for an argument of 0.0 is defined as 1.0. The sinc function is the Fourier transform of a square pulse and is used, for example, to describe the diffraction pattern of a slit. Error handling These functions should be error-proof. Return value always 0. See also VF_sin, VF_sinrpi, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sincos VD_sincos VE_sincos │ │ VFx_sincos VDx_sincos VEx_sincos │ └────────────────────────────────────────────────────────────────────────────┘ Function Sine and Cosine simultaneously Syntax #include <VFmath.h> int VF_sincos( fVector YSin, fVector YCos, fVector X, ui size ); int VFx_sincos( fVector YSin, fVector YCos, fVector X, ui size, float A, float B, float C ); Description normal versions: YSin[i] = sin( Xi ) YCos[i] = cos( Xi ) expanded versions: YSin[i] = C * sin( A*Xi+B ) YCos[i] = C * cos( A*Xi+B ) The sine and the cosine are calculated simultaneously, which is far more efficient than calculating them separately if both of them are needed. For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as fractional multiples of Pi, it is better to use VF_sincosrpi than VF_sincos. Error handling Precision errors lead to a result of 0.0 for the sine and 1.0 for the cosine (as if the input were 0.0) along with a non- zero return value, but are otherwise ignored; _matherr is not called. Other errors should not occur. Return value 0, if no error occurred, otherwise non-zero. See also VF_sincos2, VF_sincosrpi, sin, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sincos2 VD_sincos2 VE_sincos2 │ │ VFx_sincos2 VDx_sincos2 VEx_sinco2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the sine and of the cosine simultaneously Syntax #include <VFmath.h> int VF_sincos2( fVector YSin2, fVector YCos2, fVector X, ui size ); int VFx_sincos2( fVector YSin2, fVector YCos2, fVector X, ui size, float A, float B, float C ); Description normal versions: YSin2[i] = sin²( Xi ) YCos2[i] = cos²( Xi ) expanded versions: YSin2[i] = C * sin²( A*Xi+B ) YCos2[i] = C * cos²( A*Xi+B ) The squared sine and the squared cosine are calculated simultaneously, which is far more efficient than calculating them separately, if both of them are needed. Error handling Precision errors lead to a result of 0.0 for the sin² and of 1.0 for the cos² (as if the input were 0.0) along with a non- zero return value, but are otherwise ignored; _matherr is not called. Other errors should not occur. Return value 0, if no error occurred, otherwise non-zero. See also VF_sincos, sin, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sincosrpi VD_sincosrpi VE_sincosrpi │ │ VF_sincosrpi2 VD_sincosrpi2 VE_sincosrpi2 │ │ VF_sincosrpi3 VD_sincosrpi3 VE_sincosrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Sine and cosine of fractional multiples of Pi Syntax #include <VFmath.h> int VF_sincosrpi( fVector YSin, fVector YCos, iVector P, ui size, int q ); int VF_sincosrpi2( fVector YSin, fVector YCos, iVector P, ui size, int q ); int VF_sincosrpi3( fVector YSin, fVector YCos, iVector P, ui size, int q ); Description YSin[i] = sin( (P[i] / q) * Pi ) YCos[i] = cos( (P[i] / q) * Pi ) The sine and the cosine of fractional multiples of Pi are calculated. There are three versions: VF_sincosrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_sincosrpi2 should be used which is a highly optimized version reading the results from a table named VF_sintab2, if possible. If q is a multiple of 3, VF_sincosrpi3 should be used which utilizes a table named VF_sintab3. The use of VF_sincosrpi3 is a convenient way to use degrees instead of radians; if, for example, q is 180, then the unit of the elements of P is "degree". VF_sincosrpi2 and VF_sincosrpi3 work also with q values they are not optimized for; in this case, however, memory space is wasted for the (then useless) tables. Error handling These functions should be error-proof, as long as q!=0. Return value always 0 See also VF_sincos, sin, cos ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sinh VD_sinh VE_sinh │ │ VCF_sinh VCD_sinh VCE_sinh │ │ VFx_sinh VDx_sinh VEx_sinh │ │ VCFx_sinh VCDx_sinh VCEx_sinh │ └────────────────────────────────────────────────────────────────────────────┘ Function Hyperbolic sine function Syntax #include <VFmath.h> int VF_sinh( fVector Y, fVector X, ui size ); int VFx_sinh( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sinh( Xi ) expanded versions: Yi = C * sinh ( A*Xi+B ) Error handling OVERFLOW errors lead to a default result of ±HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero. See also VF_cosh, VF_exp, sinh ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sinrpi VD_sinrpi VE_sinrpi │ │ VF_sinrpi2 VD_sinrpi2 VE_sinrpi2 │ │ VF_sinrpi3 VD_sinrpi3 VE_sinrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Sine function of fractional multiples of Pi Syntax #include <VFmath.h> int VF_sinrpi( fVector Y, iVector P, ui size, int q ); int VF_sinrpi2( fVector Y, iVector P, ui size, int q ); int VF_sinrpi3( fVector Y, iVector P, ui size, int q ); Description Yi = sin( (P[i] / q) * Pi ) The sine of fractional multiples of Pi is calculated. There are three versions: VF_sinrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_sinrpi2 should be used which is a highly optimized version reading the results from a look-up table, if possible. If q is a multiple of 3, VF_sinrpi3 should be used. VF_sinrpi3 offers a convenient way to use degrees instead of radians; if, for example, q is 180, then the unit of the elements of P is "degree". VF_sinrpi2 and VF_sinrpi3 work also with q values they are not optimized for; in this case, however, memory space is wasted for the tables. Error handling These functions should be error-proof, as long as q!=0. Return value always 0 See also VF_sin, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sintab2 VD_sintab2 VE_sintab2 │ │ VF_sintab3 VD_sintab3 VE_sintab3 │ └────────────────────────────────────────────────────────────────────────────┘ Table of sine values for arguments between 0 and Pi/2 Syntax #include <xmath.h> extern float VF_sintab2[ VF_tabsz2+1 ]; extern double VD_sintab2[ VD_tabsz2+1 ]; extern extended VE_sintab2[ VE_tabsz2+1 ]; extern float VF_sintab3[ VF_tabsz3+1 ]; extern double VD_sintab3[ VD_tabsz3+1 ]; extern extended VE_sintab3[ VE_tabsz3+1 ]; Description VF_sintab2[ i ] = sin( i/(2*VF_tabsz2) * Pi ), i=0,...,VF_tabsz2 VF_sintab3[ i ] = sin( i/(2*VF_tabsz3) * Pi ), i=0,...,VF_tabsz3 These look-up tables of sine values for arguments between 0 and Pi/2 are used by VF_sinrpi2 and the other functions of that family and are also available for other purposes. The symbols VF_tabsz2 etc., denoting the size of the tables, are defined in <xmath.h>. See also VF_sinrpi2, VF_tantab2, VF_cosectab2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sort VD_sort VE_sort │ │ VI_sort VSI_sort VLI_sort VQI_sort │ │ VU_sort VUS_sort VUL_sort VUI_sort │ └────────────────────────────────────────────────────────────────────────────┘ Function Sorting into ascending or descending order Syntax #include <VFstd.h> void VF_sort( fVector Y, fVector X, ui size, int dir ); Description The vector is sorted in ascending order, if dir is positive; negative dir yields descending order. The present implementation uses the "Heapsort" algorithm. Error handling none Return value none See also VF_sortind, VF_rotate, VF_rev, qsort ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sortind VD_sortind VE_sortind │ │ VI_sortind VSI_sortind VLI_sortind VQI_sortind │ │ VU_sortind VUS_sortind VUL_sortind VUI_sortind │ └────────────────────────────────────────────────────────────────────────────┘ Function Sort the index-array of a vector Syntax #include <VFstd.h> void VF_sortind( uiVector Ind, fVector X, ui size, int dir ); Description The routine is similar to VF_sort, but this time it is the index-array of X rather than the vector X itself that is ordered. Ascending order is obtained by setting dir to any positive number. Here, ascending order means that Ind[0] will contain the index of the smallest element of X, Ind[1] the index of the second-smallest, and so on, up to Ind[size-1], the index of the largest element in X. Descending order is obtained by setting dir negative. This routine is used if other vectors are correlated with X and the correlation of the individual elements has to be maintained. After sorting the index-array, use VF_indpick (VD_indpick, VI_indpick, etc.) to actually perform the sorting of X and the other vectors correlated with X. Error handling none Return value none See also VF_sort, VF_indpick ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_spectrum VD_spectrum VE_spectrum │ └────────────────────────────────────────────────────────────────────────────┘ Function Power-density spectrum Syntax #include <VFstd.h> float VF_spectrum( fVector Spc, ui specsiz, fVector X, ui xsiz, fVector Win ); Description The data set X is analyzed for its power spectral density (PSD), i.e. the mean square amplitude. The result is stored in Spc. xsiz must be at least 2*specsiz, and specsiz has to be an integer power of 2. Internally, X is divided into xsiz*specsiz/2 segments and the average over the spectra of the individual segments is calculated. Each segment of length 2*specsiz yields the PSD for specsiz+1 frequencies (see VF_FFT). In order to keep specsiz an integer power of 2, there are only specsiz points stored in Spc and the last one, the PSD at the Nyquist frequency, is given as the return value of the function and may either be neglected (by calling the function like a void function) or stored as the last element in Spc by calling the function as Spc[specsiz] = VF_spectrum( Spc, specsiz, X, xsiz, Win ); in this case, Spc must have a length of specsiz+1. Win is a window that is applied to the data segments. The size of the Win vector must be 2*specsiz. Within the VectorLib library, three functions are available that give suitable Windows: VF_Welch, VF_Parzen, and VF_Hanning. A square window (i.e. no windowing at all) is achieved by setting all elements of Win to 1.0 using VF_equ1. Use of the square window is not recommended here, though. You may wish to test the quality of the calculated spectrum by applying the Wiener-Khinchin theorem (provided you called VF_spectrum as in the above example and stored the PSD for the Nyquist frequency): 1.0/xsize * VF_ssq( X, xsize ) must be about equal to VF_sum( Spc, specsiz+1 ). If the deviation between both results is large, the sampling interval in X probably is too large. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Example (for DOS): #include <VFstd.h> #include <VFmath.h> #include <Vgraph.h> #include <math.h> #include <conio.h> void main( void ) { fVector X, Spc, Win, Time, Freq; ui xsize=1024, specsiz=128; X = VF_vector( xsize ); Spc = VF_vector( specsiz+1 ); Win = VF_vector( 2*specsiz ); Time = VF_vector( xsize ); Freq = VF_vector( specsiz+1); VF_ramp( Time, xsize, 0.0, 200 * M_PI / xsize ); VF_ramp( Freq, specsiz+1, 0.0, (xsize / (200*M_PI)) / specsiz ); /* get a Time axis from 0 to 200 Pi and a corresponding frequency axis from 0 to the Nyquist frequency */ VF_sin( X, Time, xsize ); /* 100 periods of a sine */ VF_cmpC( X, X, xsize, 0.5 ); /* convert into asymmetric square wave */ VF_Welch( Win, 2*specsiz ); /* or another window */ Spc[specsiz] = VF_spectrum( Spc, specsiz, X, xsize, Win ); V_initGraph( "\\BorlandC\\BGI\\" ); /* give the correct BGI path! */ VF_xyAutoPlot( Freq, Spc, specsiz+1, PS_SOLID | SY_CROSS, GREEN ); getch(); /* hit any key when you have seen enough */ closegraph(); V_nfree( 5, Freq, Time, Win, Spc, X ); } Error handling If size is not a power of 2, VF_FFT (on which VF_spectrum is based) complains "Size must be an integer power of 2" and the program is aborted. Return value PSD at the Nyquist frequency See also VF_FFT, VF_convolve, VF_autocorr, VF_xcorr, VF_filter ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_splinederiv2 VD_splinederiv2 VE_splinederiv2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Generate a second-derivative table from an X-Y-table to be used for cubic-spline interpolation. Syntax #include <VFstd.h> void VF_splinederiv2( fVector Y2, fVector XTab, fVector YTab, ui size, int specify, float Yp0, float Ypn ); Description A table of second derivatives of YTab is generated to be used for cubic-spline interpolation with VF_splineinterpol. In order to get a unique solution, two additional conditions have to be specified. Setting specify to 0 yields the "natural cubic spline" with Y2 being set to zero at both end-points; in this case, Yp0 and Ypn have no influence. Setting specify to 1 yields Y2 calculated in such a way that the first(!) derivative at the zeroth and at the last position equals Yp0 and Ypn, resp. Error handling none Return value none See also VF_splineinterpol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_splineinterpol VD_splineinterpol VE_splineinterpol │ └────────────────────────────────────────────────────────────────────────────┘ Function Cubic-spline interpolation of X-Y-table values Syntax #include <VFstd.h> void VF_splineinterpol( fVector Y, fVector X, ui sizex, fVector XTab, fVector YTab, fVector Y2Tab, ui sizetab ); Description For each of the sizex elements of X, the corresponding element of Y is interpolated from the XTab-YTab value pairs. A table of second derivatives of YTab is needed that has to be generated by a call to VF_splinederiv2 prior to calling VF_splineinterpol. XTab must be ordered (either ascending or descending). All values of XTab must be distinct; otherwise a division by zero may occur and lead to a program abort. sizetab must be greater than or equal to 3. Error handling none (you have to take care yourself that the XTab values are distinct and that the YTab values are not near the limit of overflowing). Return value none See also VF_splinederiv2, VF_ratinterpol, VF_polyinterpol ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_square VD_square VE_square │ │ VCF_square VCD_square VCE_square │ │ VFx_square VDx_square VEx_square │ │ VCFx_square VCDx_square VCEx_square │ └────────────────────────────────────────────────────────────────────────────┘ Function Square Syntax #include <VFmath.h> int VF_square( fVector Y, fVector X, ui size ); int VFx_square( fVector Y, fVector X, ui size, float A, float B ); Description normal versions: Yi = Xi² expanded versions: Yi = (A*Xi+B)² Error handling OVERFLOW errors lead to a default result of HUGE_VAL. Return value 0, if no error occurred, otherwise non-zero See also VF_cubic, VF_sqrt, VF_pow, VF_ipow, VF_poly ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sqrt VD_sqrt VE_sqrt │ │ VCF_sqrt VCD_sqrt VCE_sqrt │ │ VFx_sqrt VDx_sqrt VEx_sqrt │ │ VCFx_sqrt VCDx_sqrt VCEx_sqrt │ └────────────────────────────────────────────────────────────────────────────┘ Function Square root Syntax #include <VFmath.h> int VF_sqrt( fVector Y, fVector X, ui size ); int VFx_sqrt( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = sqrt( Xi ) expanded versions: Yi = C * sqrt( A*Xi+B ) Error handling DOMAIN errors occur if, in the real-number versions, the square root of a negative numbers is requested; NAN ("not-a- number") is the default result in this case. Return value 0, if no error occurred, otherwise non-zero See also VF_square, VF_sqrt, VF_pow, VF_ipow, VF_poly ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ssq VD_ssq VE_ssq │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum-of-squares Syntax #include <VFstd.h> float VF_ssq( fVector X, ui size ); Description ssq = sum( Xi² ) Error handling none (but be careful: this function may lead to an overflow!) Return value sum of the squares of the vector elements. See also VF_sum, VF_rms, VF_ssqdevC, VF_scalprod, VF_Euclid ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ssqdevC VD_ssqdevC VE_ssqdevC │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum of the squares of the deviations from a preset value. Syntax #include <VFstd.h> float VF_ssqdevC( fVector X, ui size, float C ); Description ssqdevC = sum( (Xi - C)² ) Error handling none Return value sum of the squares of the deviations. See also VF_ssq, VF_ssqdevV, VF_avdevC, VF_sumdevC, VF_chi2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_ssqdevV VD_ssqdevV VE_ssqdevV │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum of the squares of the deviations of the elements of one vector from the corresponding elements of another Syntax #include <VFstd.h> float VF_ssqdevV( fVector X, fVector Y, ui size ); Description ssqdevV = sum( (Xi - Yi)² ) The deviation of each element of X from the corresponding element of Y is calculated and the squares of the deviations summed up and returned. Error handling none Return value sum of the squares of the deviations. See also VF_ssq, VF_ssqdevC, VF_avdevV, VF_sumdevV, VF_chi2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_store VD_store VE_store │ │ VCF_store VCD_store VCE_store │ │ VI_store VSI_store VLI_store VQI_store │ │ VU_store VUS_store VUL_store VUI_store │ └────────────────────────────────────────────────────────────────────────────┘ Function Store a vector in binary format into a stream Syntax #include <VFstd.h> VF_store( FILE *stream, fVector X, ui size ); Description size elements of X are written to stream in binary format. The stream must be already open for binary write operations. Error handling none Return value none See also fwrite, fread, VF_recall, VF_write, VF_cprint, VF_print ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subC VD_subC VE_subC │ │ VCF_subC VCD_subC VCE_subC │ │ VCF_subReC VCD_subReC VCE_subReC │ │ VI_subC VSI_subC VLI_subC VQI_subC │ │ VU_subC VUS_subC VUL_subC VUI_subC │ └────────────────────────────────────────────────────────────────────────────┘ Function Subtract a constant from each vector element Syntax #include <VFmath.h> void VF_subC( fVector Y, fVector X, ui size, float C ); void VCF_subC( cfVector Y, cfVector X, ui size, fComplex C ); void VCF_subReC( cfVector Y, cfVector X, ui size, float CRe ); Description Yi = Xi - C The complex floating-point versions exist in two variants, one for complex constants C, the other for real-valued constants CRe subtracted from the complex vector. Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_subV, VF_subrC, VF_addC, VF_mulC, VF_divC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subrC VD_subrC VE_subrC │ │ VCF_subrC VCD_subrC VCE_subrC │ │ VCF_subrReC VCD_subrReC VCE_subrReC │ │ VI_subrC VSI_subrC VLI_subrC VQI_subrC │ │ VU_subrC VUS_subrC VUL_subrC VUI_subrC │ └────────────────────────────────────────────────────────────────────────────┘ Function Reverse subtraction: subtract a vector from a constant Syntax #include <VFmath.h> void VF_subrC( fVector Y, fVector X, ui size, float C ); void VCF_subrC( cfVector Y, cfVector X, ui size, fComplex C ); void VCF_subrReC( cfVector Y, cfVector X, ui size, float CRe ); Description Yi = C - Xi The complex floating-point versions exist in two variants, one for complex constants C, the other for real-valued constants CRe from which the complex vector is subtracted. Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_addV, VF_subC, VF_mulC, VF_divC, VF_visC, VF_redC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subrV VD_subrV VE_subrV │ │ VCF_subrV VCD_subrV VCE_subrV │ │ VCF_subrReV VCD_subrReV VCE_subrReV │ │ VFx_subrV VDx_subrV VEx_subrV │ │ VCFx_subrV VCDx_subrV VCEx_subrV │ │ VCFx_subrReV VCDx_subrReV VCEx_subrReV │ │ VI_subrV VSI_subrV VLI_subrV VQI_subrV │ │ VU_subrV VUS_subrV VUL_subrV VUI_subrV │ └────────────────────────────────────────────────────────────────────────────┘ Function Subtraction in reverse order Syntax #include <VFmath.h> void VF_subrV( fVector Z, fVector X, fVector Y, ui size ); void VFx_subrV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); void VCF_subrV( cfVector Z, cfVector X, cfVector Y, ui size ); void VCF_subrReV( cfVector Z, cfVector X, fVector Y, ui size ); void VCFx_subrV( cfVector Z, cfVector X, cfVector Y, ui size, fComplex A, fComplex B ); void VCFx_subrReV( cfVector Z, cfVector X, fVector Y, ui size, fComplex A, fComplex B ); Description normal versions: Zi = Yi - Xi expanded versions: Zi = Yi - (A*Xi+B) The complex floating-point versions exist in two variants: in the first variant (e.g., VCF_subrV, VCFx_subrV), X, Y, and Z are all complex; in the second variant, Y is real-valued (e.g., VCF_subrReV - "reverse subtraction of a real vector", i.e., subtraction of a complex vector from a real vector). Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_subrC, VF_addV, VF_mulV, VF_divV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subV VD_subV VE_subV │ │ VCF_subV VCD_subV VCE_subV │ │ VCF_subReV VCD_subReV VCE_subReV │ │ VFs_subV VDs_subV VEs_subV │ │ VFx_subV VDx_subV VEx_subV │ │ VCFx_subV VCDx_subV VCEx_subV │ │ VCFx_subReV VCDx_subReV VCEx_subReV │ │ VI_subV VSI_subV VLI_subV VQI_subV │ │ VU_subV VUS_subV VUL_subV VUI_subV │ └────────────────────────────────────────────────────────────────────────────┘ Function Subtract two vectors Syntax #include <VFmath.h> void VF_subV( fVector Z, fVector X, fVector Y, ui size ); void VFs_subV( fVector Z, fVector X, fVector Y, ui size, float C ); void VFx_subV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); void VCF_subV( cfVector Z, cfVector X, cfVector Y, ui size ); void VCF_subReV( cfVector Z, cfVector X, fVector Y, ui size ); void VCFx_subV( cfVector Z, cfVector X, cfVector Y, ui size, fComplex A, fComplex B ); void VCFx_subReV( cfVector Z, cfVector X, fVector Y, ui size, fComplex A, fComplex B ); Description normal versions: Zi = Xi - Yi scaled versions: Zi = C * (Xi - Yi) expanded versions: Zi = (A*Xi+B) - Yi The complex floating-point versions exist in two variants: in the first variant (e.g., VCF_subV, VCFx_subV), X, Y, and Z are all complex; in the second variant, Y is real-valued (e.g., VCF_subReV - "subtract a real vector"). Error handling floating-point versions: none; integer versions: see chapter 5.2. Return value none See also VF_subC, VF_addV, VF_mulV, VF_divV, VF_visV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subvector VD_subvector VE_subvector │ │ VCF_subvector VCD_subvector VCE_subvector │ │ VI_subvector VSI_subvector VLI_subvector VQI_subvector │ │ VU_subvector VUS_subvector VUL_subvector VUI_subvector │ └────────────────────────────────────────────────────────────────────────────┘ Function Extract a sub-vector from the input vector Syntax #include <VFstd.h> void VF_subvector( fVector Y, ui subsize, fVector X, int samp ); Description Y[i] = X[i*samp] A sub-vector Y is extracted from X with a sampling interval samp. This means that every samp'th element is taken, up to a total of subsize elements, starting with the zeroth element of X. Since X may be an expression like XX+1000, samp does not always need to be positive, but may also take on negative values (or the trivial value of 0). X and Y have to be distinct. Instead of using a samp of 0, 1, or -1, one should use VF_equC, VF_equV, or VF_rev, respectively. Error handling none Return value none See also VF_indpick, VF_CtoRe ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subvector_... VD_subvector_... VE_subvector_... │ │ VCF_subvector_... VCD_subvector_... VCE_subvector_... │ │ ..._addC ..._addV │ │ ..._divC ..._divV │ │ ..._divrC ..._divrV │ │ ..._mulC ..._mulV │ │ ..._subC ..._subV │ │ ..._subrC ..._subrV │ └────────────────────────────────────────────────────────────────────────────┘ Function Arithmetic functions working on a sub-set of elements within a vector of one of the floating-point data types. Syntax #include <VFmath.h> void VF_subvector_addC( fVector Y, ui subsize, unsigned samp, float C ); void VF_subvector_addV( fVector Y, ui subsize, unsigned samp, fVector X ); (similarly all other functions of this family) Description ..._addC: Y[i*samp] += C, i=0,...subsize-1 ..._addV: Y[i*samp] += Xi, i=0,...subsize-1 ..._subC: Y[i*samp] -= C, i=0,...subsize-1 ..._subV: Y[i*samp] -= Xi, i=0,...subsize-1 ..._subrC: Y[i*samp] = C - Y[i*samp], i=0,...subsize-1 ..._subrV: Y[i*samp] = Xi- Y[i*samp], i=0,...subsize-1 ..._mulC: Y[i*samp] *= C, i=0,...subsize-1 ..._mulV: Y[i*samp] *= Xi, i=0,...subsize-1 ..._divC: Y[i*samp] /= C, i=0,...subsize-1 ..._divV: Y[i*samp] /= Xi, i=0,...subsize-1 ..._divrC: Y[i*samp] = C / Y[i*samp], i=0,...subsize-1 ..._divrV: Y[i*samp] = Xi / Y[i*samp], i=0,...subsize-1 The operation indicated in the suffix of the function name is perfomed on a sub-set of the elements of a vector. The sampling interval is denoted by samp: every samp'th element is taken, up to a total of subsize, starting with the zeroth one (that means, subsize is not the total size of the vector, but rather the size of the sub-set, i.e. the number of elements for which the function is performed). Notice that all operations are performed in place, i.e., the input vector itself is changed. For similar functions not included in the above list, the necessary sequence of calls is similar to the following example (which shows how to calculate the sinc function of the zeroth and then every tenth element of X, assuming that size is an integer multiple of 10): VF_subvector( Y, size/10, 10, X ); VF_sinc( Y, Y, size/10 ); VF_subvector_equV( X, size/10, 10, Y ); (However, in such cases, you would sometimes prefer the classic style of a loop with the loop-increment set to 10. Only if the desired function is not available in the math library of Borland C, the effort of copying back and forth into the dummy vector Y will pay off.) Error handling none Return value none See also VF_subvector, VF_subvector_equC, VF_subvector_equV, VF_addC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_subvector_... VD_subvector_... VE_subvector_... │ │ VCF_subvector_... VCD_subvector_... VCE_subvector_... │ │ VI_subvector_... VSI_subvector_... │ │ VLI_subvector_... VQI_subvector_... │ │ VU_subvector_... VUS_subvector_... │ │ VUL_subvector_... VUI_subvector_... │ │ ..._equC ..._equV │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialize a sub-set of elements within a vector either with a constant value or with values stored as the elements of another vector. Syntax #include <VFstd.h> void VF_subvector_equC( fVector Y, ui subsize, unsigned samp, float C ); void VF_subvector_equV( fVector Y, ui subsize, unsigned samp, fVector X ); (similarly all other functions of this family) Description ..._equC: Y[i*samp] = C, i=0,...subsize-1 ..._equV: Y[i*samp] = Xi, i=0,...subsize-1 A sub-set of the elements of a vector is overwritten according to the sampling interval samp: every samp'th element is initialized either with the constant C, or with the value specified as an element of the vector X. A total of subsize elements is initialized, starting with the zeroth one (that means, subsize is not the total size of the vector, but rather the size of the sub-set). VF_subvector_equV is the exact reverse of VF_subvector. Error handling none Return value none See also VF_subvector, VF_equC, VF_equV, VF_subvector_addC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sum VD_sum VE_sum │ │ VCF_sum VCD_sum VCE_sum │ │ VI_sum VSI_sum VLI_sum VQI_sum │ │ VU_sum VUS_sum VUL_sum VUI_sum │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum up all the elements of a vector. Syntax #include <VFstd.h> float VF_sum( fVector X, ui size ); Description sum = sum( Xi ) The sum over all elements of a vector is calculated and returned. Error handling none (but be careful: this function may easily overflow!) Return value sum of the vector elements. See also VF_runsum, VF_prod, VF_ssq, VF_ssqdevC, VF_mean ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sumabs VD_sumabs VE_sumabs │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum up the absolute values of all the elements of a vector. Syntax #include <VFstd.h> float VF_sumabs( fVector X, ui size ); Description sumabs = sum(| Xi |) Error handling none (but be careful: this function may easily overflow!) Return value sum of the absolute values of all vector elements. See also VF_sum, VF_meanabs ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sumdevC VD_sumdevC VE_sumdevC │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum of the absolute deviations from a preset value. Syntax #include <VFstd.h> float VF_sumdevC( fVector X, ui size, float C ); Description sumdevC = sum( |Xi - C| ) Error handling none Return value sum of the absolute deviations. See also VF_ssqdevC, VF_sumdevV, VF_avdevC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_sumdevV VD_sumdevV VE_sumdevV │ └────────────────────────────────────────────────────────────────────────────┘ Function Sum of the absolute deviations of the elements of one vector from the corresponding elements of another Syntax #include <VFstd.h> float VF_sumdevV( fVector X, fVector Y, ui size ); Description sumdevV = sum( |Xi - Yi| ) Error handling none Return value sum of the absolute deviations. See also VF_sum, VF_sumdevC, VF_avdevV, VF_ssqdevV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_tan VD_tan VE_tan │ │ VCF_tan VCD_tan VCE_tan │ │ VFx_tan VDx_tan VEx_tan │ │ VCFx_tan VCDx_tan VCEx_tan │ └────────────────────────────────────────────────────────────────────────────┘ Function Tangent function Syntax #include <VFmath.h> int VF_tan( fVector Y, fVector X, ui size ); int VFx_tan( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = tan ( Xi ) expanded versions: Yi = C * tan( A*Xi+B ) For large values of Xi, round-off error becomes appreciable; if the Xi values are representable as rational multiples of Pi, it is better to use VF_tanrpi than VF_tan. Error handling SING and OVERFLOW errors (for arguments very close to Pi/2) lead to a default result of ±HUGE_VAL. Precision errors lead to a default result of 0.0. Return value 0, if no error occurred, otherwise non-zero. See also VF_tan2, VF_tanrpi, VF_sin, VF_tanh, VF_atan, VF_atan2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_tan2 VD_tan2 VE_tan2 │ │ VFx_tan2 VDx_tan2 VEx_tan2 │ └────────────────────────────────────────────────────────────────────────────┘ Function Square of the tangent function Syntax #include <VFmath.h> int VF_tan2( fVector Y, fVector X, ui size ); int VFx_tan2( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = tan²( Xi ) expanded versions: Yi = C * tan²( A*Xi+B ) Calculating the squared trigonometric functions directly is faster and sometimes more accurate than first calculating the trigonometric function itself and squaring it afterwards. Error handling SING and OVERFLOW errors (for arguments close to Pi/2) lead to a default result of ±HUGE_VAL. Precision errors lead to a default result of 0.0. Return value 0, if no error occurred, otherwise non-zero. See also VF_tan, VF_tanrpi, sin ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_tanh VD_tanh VE_tanh │ │ VCF_tanh VCD_tanh VCE_tanh │ │ VFx_tanh VDx_tanh VEx_tanh │ │ VCFx_tanh VCDx_tanh VCEx_tanh │ └────────────────────────────────────────────────────────────────────────────┘ Function Hyperbolic tangent function Syntax #include <VFmath.h> int VF_tanh( fVector Y, fVector X, ui size ); int VFx_tanh( fVector Y, fVector X, ui size, float A, float B, float C ); Description normal versions: Yi = tanh( Xi ) exp( Xi ) - exp( -Xi ) = ────────────────────── exp( Xi ) + exp( -Xi ) expanded versions: Yi = C * tanh( A*Xi+B ) Error handling These functions should be error-proof. Return value always 0. See also VF_sinh, VF_exp, tanh ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_tanrpi VD_tanrpi VE_tanrpi │ │ VF_tanrpi2 VD_tanrpi2 VE_tanrpi2 │ │ VF_tanrpi3 VD_tanrpi3 VE_tanrpi3 │ └────────────────────────────────────────────────────────────────────────────┘ Function Tangent function of fractional multiples of Pi Syntax #include <VFmath.h> int VF_tanrpi( fVector Y, iVector P, ui size, int q ); int VF_tanrpi2( fVector Y, iVector P, ui size, int q ); int VF_tanrpi3( fVector Y, iVector P, ui size, int q ); Description Yi = tan( (P[i] / q) * Pi ) The tangent of fractional multiples of Pi is calculated. There are three versions: VF_tanrpi is for general use with any arbitrary denominator q. If q is a power of 2, VF_tanrpi2 should be used which is a highly optimized version using a look-up table. If q is a multiple of 3, VF_tanrpi3 should be used. VF_tanrpi2 and VF_tanrpi3 work also with q values they are not optimized for; in this case, however, memory space is wasted for the then useless tables. Error handling SING errors occur if P[i] / q is an odd multiple of 1/2; the default result is 0.0 (which is the mean of +HUGE_VAL and -HUGE_VAL). q must be non-zero; this is, however, not tested for. Return value 0, if no error occurred, otherwise non-zero. See also VF_tan, tan ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_tantab2 VD_tantab2 VE_tantab2 │ │ VF_tantab3 VD_tantab3 VE_tantab3 │ └────────────────────────────────────────────────────────────────────────────┘ Table of tangent values for arguments between 0 and Pi/2. Syntax #include <xmath.h> extern float VF_tantab2[ VF_tabsz2+1 ]; extern double VD_tantab2[ VD_tabsz2+1 ]; extern extended VE_tantab2[ VE_tabsz2+1 ]; extern float VF_tantab3[ VF_tabsz3+1 ]; extern double VD_tantab3[ VD_tabsz3+1 ]; extern extended VE_tantab3[ VE_tabsz3+1 ]; Description VF_tantab2[ i ] = tan( i/(2*VF_tabsz2) * Pi ), i=0,...,VF_tabsz2-1 VF_tantab3[ i ] = tan( i/(2*VF_tabsz3) * Pi ), i=0,...,VF_tabsz3-1 VF_tantab2[ VF_tabsz2 ] = VF_tantab3[ VF_tabsz3 ] = 0; These look-up tables of tangent values for arguments between 0 and Pi/2 are used by VF_tanrpi2 and the other functions of that family and are also available for other purposes. Since the tangent of Pi/2 is not defined, zero is stored at its place. The symbols VF_tabsz2 etc., denoting the size of the tables, are defined in <xmath.h>. See also VF_tanrpi2, VF_sintab2, VF_cosectab2 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_trunc VD_trunc VE_trunc │ │ VF_trunctoI VD_trunctoI VE_trunctoI │ │ VF_trunctoSI VD_trunctoSI VE_trunctoSI │ │ VF_trunctoLI VD_trunctoLI VE_trunctoLI │ │ VF_trunctoQI VD_trunctoQI VE_trunctoQI │ │ VF_trunctoU VD_trunctoU VE_trunctoU │ │ VF_trunctoUS VD_trunctoUS VE_trunctoUS │ │ VF_trunctoUL VD_trunctoUL VE_trunctoUL │ │ VF_trunctoUI VD_trunctoUI VE_trunctoUI │ └────────────────────────────────────────────────────────────────────────────┘ Function Rounding by "truncating" toward zero. Syntax #include <VFmath.h> int VF_trunc( fVector Y, fVector X, ui size ); int VF_trunctoI( iVector Y, fVector X, ui size ); int VF_trunctoU( uVector Y, fVector X, ui size ); (similarly all other functions of this family) Description These functions are identical to those of the VF_chop family. They have been defined in order to maintain consistency with the function name trunc defined in Turbo Pascal. For details, see VF_chop. ┌────────────────────────────────────────────────────────────────────────────┐ │ V_UtoF V_UtoD V_UtoE │ │ V_UItoF V_UItoD V_UItoE │ │ V_ULtoF V_ULtoD V_ULtoE │ │ V_UStoF V_UStoD V_UStoE │ └────────────────────────────────────────────────────────────────────────────┘ Function Data type interconversions. See V_ItoF! ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_varianceC VD_varianceC VE_varianceC │ └────────────────────────────────────────────────────────────────────────────┘ Function Variance of a one-dimensional distribution with respect to a pre-set value Syntax #include <VFstd.h> float VF_varianceC( fVector X, ui size, float C ); Description var = (1 / size) * sum( (Xi - C)² ) Error handling none Return value The variance is returned. See also VF_mean, VF_varianceV, VF_ssq, VF_ssqdevC, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_varianceCwW VD_varianceCwW VE_varianceCwW │ └────────────────────────────────────────────────────────────────────────────┘ Function "Variance with weights" of a one-dimensional distribution with respect to a pre-set value. Syntax #include <VFstd.h> float VF_varianceCwW( fVector X, fVector Wt, ui size, float C ); Description var = (1 / sum( Wti )) * sum( Wti * (Xi - C)² ) The weights need not be normalized. Error handling none Return value variance of the distribution. See also VF_meanwW, VF_varianceC, VF_varianceVwW, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_varianceV VD_varianceV VE_varianceV │ └────────────────────────────────────────────────────────────────────────────┘ Function Variance between two one-dimensional distributions. Syntax #include <VFstd.h> float VF_varianceV( fVector X, fVector Y, ui size ); Description var = (1 / size) * sum( (Xi - Yi)² ) Error handling none Return value The variance is returned. See also VF_mean, VF_varianceC, VF_ssq, VF_ssqdevV, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_varianceVwW VD_varianceVwW VE_varianceVwW │ └────────────────────────────────────────────────────────────────────────────┘ Function "Variance with weights" between two one-dimensional distributions. Syntax #include <VFstd.h> float VF_varianceVwW( fVector X, fVector Y, fVector Wt, ui size ); Description var = (1 / sum( Wti )) * sum( Wti * (Xi - Yi)² ) The weights need not be normalized. Error handling none Return value weighted variance See also VF_meanwW, VF_chi2, VF_varianceV, VF_varianceCwW, VF_linregress ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_vector VD_vector VE_vector │ │ VCF_vector VCD_vector VCE_vector │ │ VI_vector VSI_vector VLI_vector VQI_vector │ │ VU_vector VUS_vector VUL_vector VUI_vector │ └────────────────────────────────────────────────────────────────────────────┘ Function Memory allocation for a vector Syntax #include <VFstd.h> fVector VF_vector( ui size ); Description Based on memory model and environment, the most appropriate allocation procedure is chosen by these functions. Failure to allocate memory always leads to an error message and a subsequent program abort (similar to the error handling of the "new" operator in C++). To release the memory thus allocated, V_free or V_nfree should be used. Notice: the declaration of a vector (e.g., as fVector) reserves only a name, but no memory! See chapter 4.1 if you are interested in details of the implementation. Error handling If there is not enough memory available, or if size is zero, an error message "Not enough memory" is displayed and the program aborted. Models SMALL, MEDIUM, COMPACT, and LARGE only: If more than 64 kB of memory are requested, an error message "Vector > 64 kB not possible" is displayed and the program aborted. Return value Pointer to the allocated memory See also malloc, calloc ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_vector0 VD_vector0 VE_vector0 │ │ VCF_vector0 VCD_vector0 VCE_vector0 │ │ VI_vector0 VSI_vector0 VLI_vector0 VQI_vector0 │ │ VU_vector0 VUS_vector0 VUL_vector0 VUI_vector0 │ └────────────────────────────────────────────────────────────────────────────┘ Function Memory allocation for a vector and initialization of all elements with 0 Syntax #include <VFstd.h> fVector VF_vector0( ui size ); Description The functions of this family are almost identical to those of the VF_vector family; in addition to allocating memory, they initialize all elements with 0. (Calls to VF_vector and VF_vector0 may be mixed; they use the same tables to keep track of the handles and pointers). For further information, see VF_vector. Error handling If there is not enough memory available, or if size is zero, an error message "Not enough memory" is displayed and the program aborted. Models SMALL, MEDIUM, COMPACT, and LARGE only: If more than 64 kB of memory are requested, an error message "Vector > 64 kB not possible" is displayed and the program aborted. Return value A pointer to the allocated memory is returned. See also malloc, calloc ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_visC VD_visC VE_visC │ └────────────────────────────────────────────────────────────────────────────┘ Function Visibility (or contrast) function of a vector with respect to a constant Syntax #include <VFmath.h> void VF_visC( fVector Y, fVector X, ui size, float C ); Description Yi = vis( Xi, C ) = (Xi - C) / (Xi + C) These functions are generalizations of the "visibility" or "contrast" function used in optics, where the contrast between two intensities is defined as their difference divided by their sum. For Xi=C, the visibility is defined as 0, even in the case of Xi=C=0. Error handling none Return value none See also VF_redV, VF_addC, VF_subC, VF_divC, VF_visC ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_visV VD_visV VE_visV │ │ VFx_visV VDx_visV VEx_visV │ └────────────────────────────────────────────────────────────────────────────┘ Function Visibility function of one vector with respect to another Syntax #include <VFmath.h> void VF_visV( fVector Z, fVector X, fVector Y, ui size ); void VFx_visV( fVector Z, fVector X, fVector Y, ui size, float A, float B ); Description normal versions: Zi = vis( Xi, Yi ) = (Xi - Yi) / (Xi + Yi) expanded versions: Zi = vis( A*Xi+B, Yi ) For Xi=Yi, the visibility is defined as 0, even in the case of Xi=Yi=0. Error handling none Return value none See also VF_visC, VF_addV, VF_subV, VF_divV, VF_redV ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_Welch VD_Welch VE_Welch │ └────────────────────────────────────────────────────────────────────────────┘ Function "Welch" window for use in spectral analysis Syntax #include <VFstd.h> void VF_Welch( fVector X, ui size ); Description Xi = 1 - ( (i - 0.5*(size - 1)) / (0.5*(size + 1)) )² Error handling none Return value none See also VF_Parzen, VF_Hanning, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_write VD_write VE_write │ │ VCF_write VCD_write VCE_write │ │ VI_write VSI_write VLI_write VQI_write │ │ VU_write VUS_write VUL_write VUI_write │ └────────────────────────────────────────────────────────────────────────────┘ Function Write a vector in ASCII format to a stream. Syntax #include <VFstd.h> void VF_write( FILE *stream, fVector X, ui size ); Description size elements of X are written to stream in ASCII format. By default, one element is written per line. To use these functions, stream must already be open for write operations in text format. The number format and the separation of consecutive elements may be specified using VF_setWriteFormat and VF_setWriteSeparate, respectively. See these functions for details. Storing data in ASCII format is useful if the data have to be readable by human eyes, or if they are to be exported into other programs which are not able to read machine-format numbers. If avoidable, these functions should not be used for the storage of intermediate results that later have again to be read in. Instead, the function pairs of the VF_store / VF_recall family are recommended for the following reasons: conversion into ASCII format is slow, may lead to round-off errors, and requires much more disk memory than storage in machine format. Error handling none Return value none See also VF_setWriteFormat, VF_setWriteSeparate, VF_nwrite, VF_read, VF_store, fprintf, VF_cprint, VF_print ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_xcorr VD_xcorr VE_xcorr │ └────────────────────────────────────────────────────────────────────────────┘ Function Cross-correlation function of two vectors. Syntax #include <VFstd.h> void VF_xcorr( fVector Z, fVector X, fVector Y, ui size ); Description The cross-correlation function (CCF) of X and Y is calculated and stored in Z in wrap-around order: Z[0] to Z[size/2-1] contain the CCF for zero and positive lags. Beginning with the most negative lag in Z[size/2+1], the elements up to Z[size-1] contain the CCF for negative lags. Since this function assumes X to be periodic, the CCF for the most positive lag is identical to the CCF for the most negative lag. This element is stored as Z[size/2]. To get the CCF into normal order, you may call VF_rotate( Z, Z, size, size/2 ); After that, the zero point is at the position size/2. In case X is non-periodic, end effects should be avoided by the methods described in connection with VF_convolve. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. Error handling If size is not a power of 2, VF_FFT (on which VF_xcorr is based) complains "Size must be an integer power of 2" and the program is aborted. Return value none See also VF_FFT, VF_convolve, VF_autocorr, VF_spectrum ┌────────────────────────────────────────────────────────────────────────────┐ │ VI_xor VSI_xor VLI_xor VQI_xor │ │ VU_xor VUS_xor VUL_xor VUI_xor │ └────────────────────────────────────────────────────────────────────────────┘ Function Bit-wise "XOR" operation. Syntax #include <VImath.h> void VI_xor( iVector Y, iVector X, ui size, int C ); void VUL_xor( ulVector Y, ulVector X, ui size, unsigned long C ); Description Yi = (Xi) ^ C The bit-wise "exclusive OR" operation is performed on each element Xi with the bit-mask given by C (i.e., a bit is 0 in Yi, if it was either 0 or 1 both in Xi and C simultaneously. It is 1 if Xi and C differed in this bit position). Error handling none Return value none See also VI_not, VI_and, VI_or ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_xprod VD_xprod VE_xprod │ └────────────────────────────────────────────────────────────────────────────┘ Function Cross-product of two vectors. Syntax #include <VFstd.h> void VF_xprod( fVector Z, fVector X, fVector Y ); Description Z = X x Y The cross- product of X and Y is calculated. Since this operation is defined specifically for vectors representing three dimensions in the geometrical sense, there is no parameter "size" for this function. The number of elements is 3 for each of the participating vectors, implicitly. Error handling none Return value none See also VF_scalprod, VF_Euclid ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_xyAutoPlot VD_xyAutoPlot VE_xyAutoPlot │ │ VI_xyAutoPlot VSI_xyAutoPlot VLI_xyAutoPlot VQI_xyAutoPlot │ │ VU_xyAutoPlot VUS_xyAutoPlot VUL_xyAutoPlot VUI_xyAutoPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Draws a Cartesian coordinate system and plots a Y-vector against an X-vector into it. Syntax #include <Vgraph.h> void VF_xyAutoPlot( fVector X, fVector Y, ui size, unsigned form, COLORREF color ); Description A Cartesian coordinate system is drawn with automatic scaling of the axes and the vector Y is plotted against the vector X. Prior to calling VF_xyAutoPlot, the plotting routines have to be initialized by V_initGraph (for DOS programs) or V_initPlot (DOS or Windows programs). The style of the plot is determined by the parameter form which should be constructed using the symbolic constants defined in <Vgraph.h>. For the line styles, either the BGI notation or the Windows notation may be used both in DOS and Windows programs; the necessary macros for the translation are included in <Vgraph.h>. 1. Style of lines connecting adjacent data points: PS_SOLID SOLID_LINE ____ (default) PS_DOT DOTTED_LINE · · · PS_DASH DASHED_LINE - - - PS_DASHDOT CENTER_LINE -·-·- PS_DASHDOTDOT -··-·· PS_NULL NULL_LINE (no line at all) 2. Symbols used to mark data points: SY_NULL (no symbol at all) (default) SY_CROSS x SY_PLUS + SY_STAR * SY_CIRCLE o SY_BOX ▄ SY_DIAMOND SY_TRIANGLEUP SY_TRIANGLEDOWN (if you loaded this file into a Windows program, some symbols may have been lost during character conversion) 3. Fill-style of the symbols: SY_HOLLOW (no filling) (default) SY_FILLED (filled) SY_DOTTED (hollow, with a dot at the exact position of the data point) The parameter form has to be constructed by adding the appropriate line style, the symbol and its fill-style, e.g. (SOLID_LINE + SY_TRIANGLEUP). Alternatively, the bit-wise "OR" operation may be used, e.g. (PS_SOLID | SY_CIRCLE | SY_DOTTED). If any of the line styles except NULL_LINE (or PS_NULL) is chosen, each data point will be represented by at least one pixel in DOS programs. Therefore, dotted or broken lines should be specified only if there are not too many data points. Otherwise, all line styles will eventually look like SOLID_LINE. In Windows programs, these line styles will always be plotted correctly and points will be left out if necessary. Notice that NULL_LINE or PS_NULL has to be explicitly specified, if the data points are not to be connected by lines. Just writing, e.g. (SY_BOX | SY_HOLLOW) would be interpreted as using the default line style, which is SOLID_LINE. SY_NULL and SY_HOLLOW need not be specified, since these are the default symbol and fill-style, resp. For SY_NULL, SY_CROSS, SY_PLUS and SY_STAR, the choice of fill-style has no effect. The parameter color denotes the color that is to be used for the plot (the data type COLORREF is unsigned for DOS programs and unsigned long for Windows programs). See the Borland C++ function setcolor for a description of the colors available in the various graphics modes under DOS. For Windows, the colors BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW, and WHITE are defined in <Vgraph.h> by analogy with the COLORS defined in <graphics.h> for the BGI routines, i.e. for DOS programs. Thereby, portability between DOS and Windows programs is improved. For programs designed to run exclusively under Windows, it is nevertheless recommended to use fine-tuned colors defined by the RGB macro, instead of the predefined colors. The size of the symbols may be modified with the function V_setSymbolSize. The thickness of the lines may be modified using V_setLineThickness. Example of a DOS program: #include <VFstd.h> #include <VFmath.h> #include <Vgraph.h> #include <conio.h> void main( void ) { ui size=101; fVector X, Y1, Y2; V_initGraph( "C:\\BorlandC\\BGI\\" ); /* Be sure the path is correct! */ X = VF_vector( size ); Y1 = VF_vector( size ); Y2 = VF_vector( size ); VF_ramp( X, size, -1.0, 2.0/100 ); VFx_sincos( Y1, Y2, X, size, 3.1415927, 0.0, 1.0 ); VF_xyAutoPlot( X, Y1, size, PS_SOLID | SY_CROSS, LIGHTGREEN ); VF_xyDataPlot( X, Y2, size, PS_SOLID | SY_CIRCLE | SY_DOTTED, LIGHTRED ); getch(); /* interrupt execution while watching; then press any key */ closegraph(); V_nfree( 3, Y2, Y1, X ); } Under Windows, call V_initPlot instead of V_initGraph, before performing plotting operations. Error handling none Return value none See also VF_xyAutoPlot, VF_yAutoPlot, VCF_autoPlot, V_drawAxes, V_findAxes, V_setSymbolSize, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_xy2AutoPlot VD_xy2AutoPlot VE_xy2AutoPlot │ │ VI_xy2AutoPlot VSI_xy2AutoPlot VLI_xy2AutoPlot VQI_xy2AutoPlot │ │ VU_xy2AutoPlot VUS_xy2AutoPlot VUL_xy2AutoPlot VUI_xy2AutoPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Draws a Cartesian coordinate system and plots two X-Y vector pairs into it. Syntax #include <Vgraph.h> void VF_xy2AutoPlot( fVector X1, fVector Y1, ui size1, unsigned form1, COLORREF color1, fVector X2, fVector Y2, ui size2, unsigned form2, COLORREF color2 ); Description The vector Y1 is plotted against the vector X1 and Y2 against X2 after automatically drawing a Cartesian coordinate system. For a description of the parameters form1, form2, and color1, color2, see VF_xyAutoPlot. Prior to calling VF_xy2AutoPlot, the plotting routines have to be initialized by V_initGraph or V_initPlot. Error handling none Return value none See also VF_xyAutoPlot, VF_yAutoPlot, VCF_autoPlot, V_drawAxes, V_findAxes ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_xyDataPlot VD_xyDataPlot VE_xyDataPlot │ │ VI_xyDataPlot VSI_xyDataPlot VLI_xyDataPlot VQI_xyDataPlot │ │ VU_xyDataPlot VUS_xyDataPlot VUL_xyDataPlot VUI_xyDataPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function X-Y-plot into an existing Cartesian coordinate system. Syntax #include <Vgraph.h> void VF_xyDataPlot( fVector X, fVector Y, ui size, unsigned form, COLORREF color ); Description The vector Y is plotted against the vector X into a Cartesian coordinate system drawn by a prior call to one of the AutoPlot functions or to V_drawAxes. For a description of the parameters form and color, see VF_xyAutoPlot. Error handling none Return value none See also VF_xyAutoPlot, VF_yAutoPlot, VCF_autoPlot, V_drawAxes, V_findAxes ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_yAutoPlot VD_yAutoPlot VE_yAutoPlot │ │ VI_yAutoPlot VSI_yAutoPlot VLI_yAutoPlot VQI_yAutoPlot │ │ VU_yAutoPlot VUS_yAutoPlot VUL_yAutoPlot VUI_yAutoPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Draws a Cartesian coordinate system and plots each element of a Y-vector against its index. Syntax #include <Vgraph.h>. void VF_yAutoPlot( fVector Y, ui size, unsigned form, COLORREF color ); Description A Cartesian coordinate system is automatically scaled and drawn. Each element of the vector Y is plotted against its index into this coordinate system. For a description of the parameters form and color, see VF_xyAutoPlot. The plotting routines have to be initialized by V_initGraph or V_initPlot prior to calling VF_yAutoPlot. Error handling none Return value none See also VF_yDataPlot, VF_y2AutoPlot, VF_xyAutoPlot, VCF_autoPlot, V_drawAxes, V_findAxes, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_y2AutoPlot VD_y2AutoPlot VE_y2AutoPlot │ │ VI_y2AutoPlot VSI_y2AutoPlot VLI_y2AutoPlot VQI_y2AutoPlot │ │ VU_y2AutoPlot VUS_y2AutoPlot VUL_y2AutoPlot VUI_y2AutoPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Draws a Cartesian coordinate system and plots two Y-vectors, taking the index as the X-axis. Syntax #include <Vgraph.h> void VF_y2AutoPlot( fVector Y1, ui size1, unsigned form1, COLORREF color1, fVector Y2, ui size2, unsigned form2, COLORREF color2 ); Description A Cartesian coordinate system is automatically scaled and drawn. Each element of the vectors Y1 and Y2 is plotted at the X-position given by its index. For a description of the parameters form1, form2, and color1, color2, see VF_xyAutoPlot. The plotting routines have to be initialized by V_initGraph or V_initPlot prior to calling VF_yAutoPlot. Error handling none Return value none See also VF_yDataPlot, VF_y2AutoPlot, VF_xyAutoPlot, VCF_autoPlot, V_drawAxes, V_findAxes, chapter 4.11 ┌────────────────────────────────────────────────────────────────────────────┐ │ VF_yDataPlot VD_yDataPlot VE_yDataPlot │ │ VI_yDataPlot VSI_yDataPlot VLI_yDataPlot VQI_yDataPlot │ │ VU_yDataPlot VUS_yDataPlot VUL_yDataPlot VUI_yDataPlot │ └────────────────────────────────────────────────────────────────────────────┘ Function Plots a Y-vector into an existing Cartesian coordinate system, taking the index as the X-axis. Syntax #include <Vgraph.h> void VF_yDataPlot( fVector Y, ui size, unsigned form, COLORREF color ); Description Each element of the vector Y is plotted into a Cartesian coordinate system that has to be already drawn by a prior call to one of the AutoPlot functions or to V_drawAxes. The X- position is given by the index of the Y-element to be plotted. For a description of the parameters form and color, see VF_xyAutoPlot. Error handling none Return value none See also VF_yAutoPlot, VF_y2AutoPlot, VF_xyAutoPlot, VCF_autoPlot, V_drawAxes, V_findAxes, chapter 4.11 **************************************************************************** * * ******* 9. Non-vectorized Functions ******* * * ***************************************************************************** There are a few non-vectorized functions, stemming from CMATH and XMATH, which are necessary to use VectorLib. They are described here: ┌────────────────────────────────────────────────────────────────────────────┐ │ fcplx dcplx ecplx │ └────────────────────────────────────────────────────────────────────────────┘ Function Initialization of complex numbers Syntax #include <VecLib.h> fComplex fcplx( float ReVal, float ImVal ); (similarly dcplx, ecplx) Description These functions allow to generate complex numbers of the three complex data types fComplex, dComplex, and eComplex. CMATH offers overloaded versions of these functions for C++. See CMATH.TXT for details. fcplx should be used, whenever temporary complex variables are needed as arguments for functions. In this case, fcplx replaces the less elegant direct assignment of the real and imaginary parts. Example z.Re = 3.0; z.Im = 4.0; VCF_equC( X, size, z ); /* less convenient */ VCF_equC( Y, size, fcplx( 3.0, 4.0 )); /* easier */ Error handling none Return value the generated complex number ┌────────────────────────────────────────────────────────────────────────────┐ │ quadtod _quadtold │ └────────────────────────────────────────────────────────────────────────────┘ Function convert a quad into a double or long double. Syntax #include <VecLib.h> double quadtod( quad x ); long double _quadtold( quad x ); Description These functions, along with their counterpart, setquad, provide the necessary interface for the use of the data type quad within Borland C/C++. If, e.g., the value of a quad (say, of x) has to be printed, this must be done by a function call like printf( "% 20.0Lf", _quadtold( x )); Error handling none Return value the value of x is returned as a double or long double. ┌────────────────────────────────────────────────────────────────────────────┐ │ isint isintl │ └────────────────────────────────────────────────────────────────────────────┘ Function tests if a number is a whole number Syntax #include <xmath.h> int isint( double x ); int isintl( long double x ); Description Returns TRUE (a value different from 0), if x is an integer number. FALSE (a value of 0) is returned, if x contains a non- zero fractional part. Error handling none Return value see above ┌────────────────────────────────────────────────────────────────────────────┐ │ log2 log2l │ └────────────────────────────────────────────────────────────────────────────┘ Function Binary logarithm Syntax #include <xmath.h> double log2( double x ); long double log2l( long double x ); Description The logarithm of the argument to the basis 2 is calculated and the result returned. Error handling A DOMAIN error with NAN ("not-a-number") as return value results from x < 0 (including -0). A SING error with -HUGE_VAL as return value results from x=0. The handling of both errors can be modified via _matherr or _matherrl, resp. Return value The binary logarithm of the argument is returned. See also log, logl, log10, log10l, VF_log2 ┌────────────────────────────────────────────────────────────────────────────┐ │ setquad │ └────────────────────────────────────────────────────────────────────────────┘ Function converts a long double into a quad. Syntax #include <VecLib.h> quad setquad( long double x ); Description This function, along with its counterparts, quadtod and _quadtold, provides the necessary interface for the use of the data type quad within Borland C/C++. If, e.g., quad parameters are required by a function, they have to be passed either as existing variables of this data type or as in the following example: VQI_addC( QI2, QI1,size, setquad( 53563369.L )); Error handling none Return value the value of x is returned as a quad. **************************************************************************** * * ******* 10. VectorLib Error Messages ******* * * **************************************************************************** Just as with any C or C++ program, errors occurring within mathematical functions lead to the appropriate error messages. See chapter 5 of this documentation (in the file HANDBOOK.TXT) and the description of _matherr in the Borland C++ documentation for details. Apart from math errors, there are some run-time errors specific to VectorLib routines. These errors lead to the messages noted below. The name of the function where the error occurred is not always exactly the name you wrote in your program. Instead of the prefix VI_, the message will read VLI_ or VSI_, depending on the memory model used. Similarly, instead of VU_, you will find VUL_ or VUS_, and VFs_FFT or VFl_FFT is substituted for VF_FFT, again depending on the memory model. The reason for this behavior is that many functions share code and even names. ┌────────────────────────────────────────────────────────────────────────────┐ │ Cannot free non-existent vector. │ └────────────────────────────────────────────────────────────────────────────┘ You called V_free or V_nfree for a vector that has no memory allocated. Program execution is continued without freeing anything. ┌────────────────────────────────────────────────────────────────────────────┐ │ Cannot scale symbols by more than a factor of 50. │ └────────────────────────────────────────────────────────────────────────────┘ (Windows only.) The symbols used in VectorLib plotting functions cannot be magnified by more than a factor of 50 (which means already filling the screen with a single symbol). Program execution is continued with a value of 50.0. ┌────────────────────────────────────────────────────────────────────────────┐ │ Cannot use line thicker than 500 pixels. │ └────────────────────────────────────────────────────────────────────────────┘ (Windows only.) The lines used in VectorLib plotting functions cannot be thicker than 500 pixels (which is already nonsense). Program execution is continued with a value of 500. ┌────────────────────────────────────────────────────────────────────────────┐ │ Cannot use requested format (too many entries per line). │ └────────────────────────────────────────────────────────────────────────────┘ This error occurs with the printing functions. The parameter nperline was chosen too large. The function automatically selects the maximum nperline possible and continues execution, but you should nevertheless consider adapting your program. ┌────────────────────────────────────────────────────────────────────────────┐ │ Invalid parameter(s). │ └────────────────────────────────────────────────────────────────────────────┘ In some functions, certain combinations of input parameters are illegal. For example, it is not possible to perform a 9-point interpolation on only 5 data points. ┌────────────────────────────────────────────────────────────────────────────┐ │ Not enough memory. │ └────────────────────────────────────────────────────────────────────────────┘ You are trying to allocate memory, but there is not enough left. This error occurs during calls to VF_vector etc. or to functions which need to allocate their own working space. Try these solutions: * Look out for vectors that might be no longer needed and free them as soon as possible. Be sure that any vectors allocated in subroutines are freed before leaving the subroutine. * If you need to work with large amounts of data, the memory model FLAT should be used, working with Win32, WindowsNT, or Windows95. * Store data intermediately on disk, using VF_store, and retrieve them using VF_recall, when needed. This method is slow and should be used only if really necessary. ┌────────────────────────────────────────────────────────────────────────────┐ │ Not possible with fewer than n elements. │ └────────────────────────────────────────────────────────────────────────────┘ Some functions require a minimum size of n elements of the vector processed. ┌────────────────────────────────────────────────────────────────────────────┐ │ Not possible with more than n elements. │ └────────────────────────────────────────────────────────────────────────────┘ Some functions are limited to a maximum size of n elements. This is true, for example, for VF_polyinterpol, where only up to 10 table elements may be used for the each interpolation. ┌────────────────────────────────────────────────────────────────────────────┐ │ Size must be an integer power of 2. │ └────────────────────────────────────────────────────────────────────────────┘ For all functions using - explicitly or implicitly - Fast Fourier Transform methods, the size has to be an integer power of 2. Enlarge or truncate your vector(s) to meet that condition. ┌────────────────────────────────────────────────────────────────────────────┐ │ Vector > 64 kB not possible. │ └────────────────────────────────────────────────────────────────────────────┘ * Either you are trying to allocate a vector whose size exceeds 64 kB in a memory model other than HUGE or FLAT. If you need larger vectors, you have to switch to one of these models. * Or you are already in the HUGE model and attempt to process a huge vector in a function where the size is limited to 64 kB even in the HUGE model. This might happen, e.g., if the table is too large in one of the interpolation routines. In this case, you must either use the model FLAT or split up your problem into smaller vectors. ┌────────────────────────────────────────────────────────────────────────────┐ │ Vectors must not be identical. │ └────────────────────────────────────────────────────────────────────────────┘ In some functions where more than one input vector is used to calculate more than one output vector, attention has to be paid, which output vector may or may not overwrite which input vector. See the specification of the function where the error occurred. **************************************************************************** * * ******* E N D ******* * * ***************************************************************************** **************************************************************************** Copyright for OptiVec software and documentation (C) 1996-1998 Martin Sander. All rights reserved!